跳到主要内容

Python 虚拟环境管理

虚拟环境是 Python 项目管理的基础，它为每个项目创建独立的 Python 运行环境，避免依赖冲突。本章将深入介绍虚拟环境的原理和各种管理工具。

为什么需要虚拟环境？​

依赖冲突问题​

假设你有两个项目：

  • 项目 A 需要 requests==2.28.0
  • 项目 B 需要 requests==2.31.0

如果在系统全局安装，两个项目会相互冲突。虚拟环境解决了这个问题，每个项目可以有自己独立的依赖版本。

虚拟环境的核心作用​

  1. 依赖隔离：每个项目有独立的包安装目录
  2. 版本管理：不同项目可以使用同一包的不同版本
  3. 环境可复现：可以精确记录和重建项目依赖
  4. 系统保护：避免污染系统 Python 环境

venv 模块（标准库）​

venv 是 Python 3.3+ 内置的虚拟环境模块，轻量且无需额外安装。

创建虚拟环境​

python -m venv .venv

这会在当前目录创建 .venv 文件夹，包含：

.venv/
├── bin/              # Linux/macOS
│   ├── activate      # 激活脚本
│   ├── python        # Python 解释器（符号链接）
│   └── pip           # pip（符号链接）
├── Scripts/          # Windows
│   ├── activate.bat
│   ├── Activate.ps1
│   ├── python.exe
│   └── pip.exe
├── lib/
│   └── python3.x/
│       └── site-packages/  # 安装的包
└── pyvenv.cfg        # 配置文件

激活虚拟环境​

# Linux/macOS (bash/zsh)
source .venv/bin/activate

# Linux/macOS (fish)
source .venv/bin/activate.fish

# Linux/macOS (csh/tcsh)
source .venv/bin/activate.csh

# Windows (cmd)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

激活后，命令行提示符会显示环境名称：

(.venv) $ python --version

解释：激活脚本会修改 PATH 环境变量，将虚拟环境的 bin 目录放在最前面，这样 python 和 pip 命令就会使用虚拟环境中的版本。

退出虚拟环境​

deactivate

venv 常用选项​

python -m venv [选项] 环境目录

--system-site-packages  # 允许访问系统 site-packages
--copies                # 复制文件而非符号链接（Windows 默认）
--symlinks              # 使用符号链接（Unix 默认）
--clear                 # 清除现有环境目录内容
--upgrade               # 升级环境到当前 Python 版本
--without-pip           # 不安装 pip
--prompt PROMPT         # 自定义提示符前缀
--upgrade-deps          # 升级 pip 到最新版本

示例：

python -m venv .venv --prompt myproject
python -m venv .venv --system-site-packages

不激活直接使用​

虚拟环境激活不是必须的，可以直接使用完整路径：

.venv/bin/python script.py
.venv/bin/pip install requests

这种方式适合脚本和自动化场景。

检测是否在虚拟环境中​

import sys

def in_virtualenv():
    return sys.prefix != sys.base_prefix

if in_virtualenv():
    print(f"当前在虚拟环境中: {sys.prefix}")
else:
    print("不在虚拟环境中")

解释：

  • sys.prefix：当前 Python 环境的根目录
  • sys.base_prefix：基础 Python 安装目录
  • 在虚拟环境中，两者不同

pip 包管理​

安装包​

pip install requests              # 安装最新版
pip install requests==2.28.0      # 安装指定版本
pip install requests>=2.28.0      # 安装最低版本
pip install "requests>=2.28,<3.0" # 版本范围
pip install -e ./my-package       # 可编辑模式安装
pip install git+https://github.com/user/repo.git  # 从 Git 安装

管理依赖​

pip list                    # 列出已安装的包
pip list --outdated         # 列出过时的包
pip show requests           # 显示包详情
pip freeze                  # 导出依赖列表
pip freeze > requirements.txt

pip install -r requirements.txt  # 从文件安装
pip install -r requirements.txt --upgrade  # 升级所有依赖

requirements.txt 最佳实践​

# requirements.txt

# 生产依赖
requests==2.31.0
flask==3.0.0
sqlalchemy==2.0.23

# 使用环境标记
pywin32==306; sys_platform == 'win32'

分离开发和生产依赖：

# requirements.txt（生产）
requests==2.31.0
flask==3.0.0

# requirements-dev.txt（开发）
-r requirements.txt
pytest==7.4.0
black==23.0.0
mypy==1.7.0

现代依赖管理工具​

Poetry​

Poetry 是现代化的 Python 依赖管理工具，提供完整的项目管理功能。

安装​

pip install poetry

初始化项目​

poetry new myproject
cd myproject

或为现有项目初始化：

poetry init

pyproject.toml 配置​

[tool.poetry]
name = "myproject"
version = "0.1.0"
description = "A sample project"
authors = ["Your Name <[email protected]>"]

[tool.poetry.dependencies]
python = "^3.10"
requests = "^2.31.0"
flask = "^3.0.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
black = "^23.0.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

常用命令​

poetry install              # 安装所有依赖
poetry install --only main  # 只安装生产依赖
poetry add requests         # 添加依赖
poetry add pytest --group dev  # 添加开发依赖
poetry remove requests      # 移除依赖
poetry update               # 更新所有依赖
poetry show                 # 显示依赖树
poetry show --tree          # 显示依赖树结构
poetry shell                # 激活虚拟环境
poetry run python app.py    # 在虚拟环境中运行命令
poetry build                # 构建分发包
poetry publish              # 发布到 PyPI

解释：Poetry 自动创建和管理虚拟环境，无需手动激活。poetry.lock 文件锁定精确版本，确保可复现性。

pipenv​

Pipenv 结合了 pip 和 virtualenv 的功能。

pip install pipenv

pipenv install              # 创建环境并安装依赖
pipenv install requests     # 安装包
pipenv install pytest --dev # 安装开发依赖
pipenv shell                # 激活环境
pipenv run python app.py    # 运行命令
pipenv graph                # 显示依赖树
pipenv lock                 # 生成 Pipfile.lock

Pipfile 示例：

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]
requests = "*"
flask = ">=3.0.0"

[dev-packages]
pytest = "*"

[requires]
python_version = "3.11"

uv（新一代工具）​

uv 是用 Rust 编写的超快 Python 包管理器。

pip install uv

uv venv                     # 创建虚拟环境
uv pip install requests     # 安装包（比 pip 快 10-100 倍）
uv pip install -r requirements.txt
uv pip sync requirements.txt  # 精确同步依赖

Conda（科学计算首选）​

Conda 是 Anaconda/Miniconda 提供的跨语言包管理器，特别适合数据科学项目。

安装​

推荐安装 Miniconda（精简版）：

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

环境管理​

conda create -n myproject python=3.11  # 创建环境
conda create -n ml python=3.11 numpy pandas scikit-learn  # 创建并安装包

conda activate myproject   # 激活环境
conda deactivate           # 退出环境

conda env list             # 列出所有环境
conda env remove -n myproject  # 删除环境

conda env export > environment.yml  # 导出环境
conda env create -f environment.yml  # 从文件创建环境

包管理​

conda install numpy        # 安装包
conda install -c conda-forge pandas  # 从指定频道安装
conda update numpy         # 更新包
conda remove numpy         # 移除包
conda list                 # 列出已安装的包
conda search numpy         # 搜索包

environment.yml 示例​

name: myproject
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.11
  - numpy=1.26
  - pandas=2.1
  - pip
  - pip:
    - requests==2.31.0

工具选择建议​

场景推荐工具理由
简单项目venv + pip内置工具，无需额外安装
应用开发Poetry完整的项目管理，依赖锁定
数据科学Conda支持 C 扩展库，预编译包
快速安装uv极快的安装速度
团队协作Poetry统一的开发体验

最佳实践​

1. 环境目录命名​

.venv/     # 推荐：隐藏目录，不影响项目结构
venv/      # 常见：非隐藏目录
env/       # 另一种常见命名

2. Git 忽略​

.venv/
venv/
env/
*.pyc
__pycache__/

3. 项目结构​

myproject/
├── .venv/              # 虚拟环境（不提交）
├── src/
│   └── myproject/
│       └── __init__.py
├── tests/
├── pyproject.toml      # 项目配置
├── poetry.lock         # 依赖锁定（提交）
└── README.md

4. 版本锁定​

生产环境必须锁定精确版本：

requests==2.31.0
flask==3.0.0

而非：

requests>=2.31.0
flask>=3.0.0

5. 使用 pyproject.toml​

现代 Python 项目推荐使用 pyproject.toml 作为统一配置文件：

[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.31.0",
    "flask>=3.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
]

[project.scripts]
myapp = "myproject.main:main"

安装：

pip install -e .           # 安装项目（可编辑模式）
pip install -e ".[dev]"    # 安装项目及开发依赖

小结​

本章我们学习了：

  1. 虚拟环境的作用和原理
  2. venv 模块的使用方法
  3. pip 包管理技巧
  4. Poetry 现代依赖管理
  5. Conda 科学计算环境
  6. 各种工具的选择建议
  7. 最佳实践

练习​

  1. 使用 venv 创建一个虚拟环境并安装 requests
  2. 使用 Poetry 创建一个新项目并管理依赖
  3. 使用 Conda 创建一个数据科学环境
  4. 编写 requirements.txt 和 requirements-dev.txt

延伸阅读​