您现在的位置：程式碼之家 >> 編程語言 > >> 更多程式語言 >> 更多程式設計知識

Python 虛擬環境：virtualenv 與 virtualenvwrapper 完整教學

編輯：更多程式設計知識

虛擬環境是 Python 專案依賴隔離、版本管理、部署一致性的基礎工具。virtualenv 建立獨立 Python 環境，virtualenvwrapper 提供便捷管理指令。本文完整涵蓋安裝、建立、啟動、套件管理、專案整合、遷移、Python 3 內建 venv 對比與最佳實務。

核心概念與優勢

隔離性：各專案擁有獨立 site-packages，版本衝突零風險。
權限自由：無需 sudo 安裝套件，用戶目錄即可。
可重現性：requirements.txt 鎖定依賴版本，團隊/部署環境一致。
多 Python 版本：同機器支援不同專案用不同 Python 版本。

virtualenv 安裝與基本使用

安裝


# 系統級安裝（需 sudo）
sudo pip install virtualenv

# 或用戶級安裝
pip install --user virtualenv

# 確認版本
virtualenv --version

建立虛擬環境


# 專案目錄下建立
cd myproject
virtualenv venv              # 預設繼承系統 site-packages
virtualenv --no-site-packages venv  # 完全隔離（舊版預設，新版加參數）

# 指定 Python 版本
virtualenv -p python3.8 venv38
virtualenv -p /usr/bin/python3.11 venv311

啟動與停用


# Linux/macOS
source venv/bin/activate
# 提示字元變化：(venv) user@host:~/myproject$

# Windows CMD
venv\Scripts\activate.bat

# Windows PowerShell
venv\Scripts\Activate.ps1

# 停用
deactivate

環境內套件管理


# 確認使用環境內 pip
which pip   # /path/to/myproject/venv/bin/pip

# 安裝套件
pip install requests django==4.2

# 查看已安裝
pip list
pip freeze

# 匯出需求檔
pip freeze > requirements.txt

# 從需求檔安裝（部署/新環境）
pip install -r requirements.txt

virtualenvwrapper：進階管理工具

安裝與設定


# 安裝
pip install virtualenvwrapper

# 設定 shell（~/.bashrc 或 ~/.zshrc）
export WORKON_HOME=$HOME/.virtualenvs
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
source /usr/local/bin/virtualenvwrapper.sh  # 路徑視安裝位置調整

# 重新載入
source ~/.bashrc

核心指令速查

專案目錄綁定


# 建立環境並綁定專案目錄
mkvirtualenv -a /path/to/myproject myproject

# 之後 workon myproject 會自動 cd 到專案目錄
workon myproject
# (myproject) user@host:~/myproject$

Python 3 內建 venv 模組（無需額外安裝）


# 建立
python3 -m venv venv

# 啟動
source venv/bin/activate

# 違異：venv 較輕量、標準庫內建、無 virtualenvwrapper 整合
# 功能足夠大多數需求，建議新專案優先使用

進階技巧與最佳實務

1. 需求檔最佳實務


# requirements.txt（部署用，版本鎖定）
Django==4.2.7
requests==2.31.0
psycopg2-binary==2.9.9

# requirements-dev.txt（開發用，含測試工具）
-r requirements.txt
pytest==7.4.2
black==23.7.0
flake8==6.0.0

# 安裝開發環境
pip install -r requirements-dev.txt

2. pip-tools 編譯需求（進階版本鎖定）


# pip install pip-tools
# requirements.in（鬆綁版本）
django
requests
psycopg2-binary

# 編譯鎖定版本
pip-compile requirements.in  # 產生 requirements.txt

# 同步環境（安裝/移除/升級到完全一致）
pip-sync requirements.txt

3. 環境遷移與打包


# virtualenv --relocatable（已棄用，不推薦）
# 現代做法：重新建立環境 + pip-sync

# Docker 部署範例
# Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "main.py"]

4. 多 Python 版本管理：pyenv


# 安裝 pyenv（管理 Python 版本）
# 列出可安裝版本
pyenv install --list

# 安裝特定版本
pyenv install 3.11.5

# 專案指定版本
cd myproject
pyenv local 3.11.5  # 建立 .python-version

# 搭配 virtualenv
pyenv virtualenv 3.11.5 myproject-env
pyenv local myproject-env

5. IDE 整合

VS Code：Ctrl+Shift+P → Python: Select Interpreter 選擇環境內 python。
PyCharm：Settings → Project Interpreter → Add → Existing Environment → 指向 venv/bin/python。
Vim/Neovim：pyenv + virtualenvwrapper + jedi/pylsp。

常見問題排查

指令	功能	範例
mkvirtualenv	建立並啟動環境	mkvirtualenv myproject
workon	列出/切換環境	workon / workon myproject
rmvirtualenv	刪除環境	rmvirtualenv oldproject
deactivate	離開當前環境	deactivate
lsvirtualenv	列出所有環境	lsvirtualenv
cpvirtualenv	複製環境	cpvirtualenv src dest
showvirtualenv	顯示環境詳細資訊	showvirtualenv

問題	原因	解決
ImportError 無法匯入已安裝套件	未啟動虛擬環境、IDE 用錯解譯器	確認提示字元有 (venv)、IDE 設定正確路徑
pip install 權限錯誤	未在虛擬環境、嘗試寫入系統目錄	啟動虛擬環境、或用 --user
Python 版本不符	環境建立時用錯 python	重建環境：virtualenv -p python3.11 venv
requirements.txt 版本衝突	依賴關係複雜	用 pip-tools pip-compile 解析

總結

虛擬環境是 Python 專案專業開發的**標準配備**。新專案建議：**Python 3.3+ 直接用內建 venv**，搭配 pip-tools 管理依賴；需要統一管理多環境時加裝 virtualenvwrapper；多 Python 版本專案用 pyenv + pyenv-virtualenv。核心流程：建立 → 啟動 → pip install → freeze → requirements.txt → 部署同步。養成「每專案一環境」習慣，徹底解決依賴地獄。