Python 虛擬環境最佳實踐：pyenv + venv + pip 完整指南

Python 虛擬環境的最佳實踐是結合 pyenv、venv 與 pip 三層工具：pyenv 負責管理系統上的多個 Python 版本，venv 為每個專案創建獨立的隔離環境，pip 則處理套件依賴管理。這種組合既能實現版本控制，又能確保專案間的依賴互不干擾，是現代 Python 開發的標準做法。

為什麼需要 Python 虛擬環境？

在開發多個 Python 專案時，常會遇到依賴版本衝突的問題。例如專案 A 需要 Django 2.x，而專案 B 需要 Django 4.x，若在同一環境中安裝會造成相容性錯誤。虛擬環境透過隔離機制，讓每個專案擁有獨立的套件空間，徹底解決版本衝突問題。

此外，虛擬環境也便於專案交付與部署。團隊成員或部署伺服器只需執行 pip install -r requirements.txt，即可重現完全一致的開發環境，大幅提升協作效率與部署穩定性。

pyenv：管理多版本 Python

pyenv 是一款 Python 版本管理工具，允許在同一系統上安裝、切換多個 Python 版本。這對於需要測試不同 Python 版本相容性或維護legacy專案的開發者特別實用。

安裝 pyenv（以 macOS/Linux 為例）

# 安裝依賴（Ubuntu/Debian）
$ sudo apt-get update
$ sudo apt-get install -y build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev curl libncursesw5-dev \
  xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

# 安裝 pyenv
$ curl https://pyenv.run | bash

基本操作指令

值得注意的是，pyenv 只管理 Python 直譯器本身，不負責虛擬環境的創建。虛擬環境需搭配 venv 使用。

venv：創建隔離的專案環境

venv 是 Python 3.3+ 內建的虛擬環境模組，無需額外安裝即可使用。它會在指定目錄建立獨立的 Python 環境，包含專屬的 bin/（Linux/macOS）或 Scripts/（Windows）資料夾，以及獨立的 site-packages 目錄。

創建與啟用虛擬環境

# 進入專案目錄
$ cd myproject

# 創建名為 venv 的虛擬環境
$ python -m venv venv

# 啟用虛擬環境（Linux/macOS）
$ source venv/bin/activate

# 啟用虛擬環境（Windows）
$ venv\Scripts\activate

# 確認啟用成功，命令列會顯示 (venv) 前綴
(venv) $ python --version
Python 3.11.0

退出虛擬環境

# 退出虛擬環境
$ deactivate

使用 venv 的優勢在於它是 Python 標準庫的一部分，無需安裝第三方套件，且與 pip 完美整合，是建立專案隔離環境的首選方案。

pip：依賴管理與套件安裝

pip 是 Python 的套件管理工具，用於安裝、升級、移除第三方套件。在虛擬環境中使用 pip 安裝的套件，只會存在於該環境內，不會影響系統或其他專案。

常用 pip 指令

# 升級 pip 本身
(venv) $ pip install --upgrade pip

# 安裝指定套件
(venv) $ pip install requests flask

# 安裝特定版本
(venv) $ pip install django==4.2.0

# 查看已安裝套件
(venv) $ pip list

# 匯出依賴清單至檔案
(venv) $ pip freeze > requirements.txt

# 從檔案安裝依賴
(venv) $ pip install -r requirements.txt

# 升級套件
(venv) $ pip install --upgrade requests

# 移除套件
(venv) $ pip uninstall requests

最佳實踐：使用 requirements.txt

建議每個專案都維護一份 requirements.txt 檔案，清楚記錄所有依賴及其版本。這是團隊協作與部署的最佳實踐，可確保所有人使用相同的套件環境。

requirements.txt 範例內容：

requests==2.31.0
flask==3.0.0
django==4.2.7
pandas==2.1.3
numpy==1.26.2

若要產生不含系統套件的乾淨清單，可使用 pip-tools 工具的 pip-compile 命令，自動解析依賴並產生嚴謹的版本指定。

完整工作流程：整合使用 pyenv + venv + pip

以下示範從零開始建立 Python 專案環境的完整流程：

# 1. 使用 pyenv 安裝並設定 Python 版本
$ pyenv install 3.11.0
$ pyenv local 3.11.0

# 2. 創建專案目錄並進入
$ mkdir myproject && cd myproject

# 3. 使用 venv 創建虛擬環境
$ python -m venv venv

# 4. 啟用虛擬環境
$ source venv/bin/activate

# 5. 升級 pip 並安裝專案依賴
(venv) $ pip install --upgrade pip
(venv) $ pip install -r requirements.txt

# 6. 開始開發...
# 完成後匯出依賴清單
(venv) $ pip freeze > requirements.txt

# 7. 離開虛擬環境
(venv) $ deactivate

這套流程的核心理念是：pyenv 管理系統層級的 Python 版本，venv 管理專案層級的隔離環境，pip 管理環境內的套件依賴。三者各司其職，形成完善的開發環境架構。

對於需要更進階依賴管理的開發者，可考慮使用 Poetry 或 Pipenv 等工具，它們整合了虛擬環境與依賴管理功能，但學習曲線較高。若團隊已熟悉 pip + venv 的組合，上述流程已能滿足絕大多數需求。