Python 虚拟环境与包管理

2025-11-24 约 1874 字预计阅读 4 分钟

学习目标：掌握 Python 虚拟环境的创建与使用，理解包管理的最佳实践，学会使用现代工具链管理项目依赖。

1. 为什么需要虚拟环境

1.1 依赖冲突问题

项目 A 需要 Django 3.2
项目 B 需要 Django 4.2
                    ↓
        全局环境只能装一个版本 → 冲突！

解决方案：每个项目使用独立的虚拟环境

1.2 虚拟环境的作用

隔离依赖：每个项目有独立的包环境
版本锁定：避免全局包版本升级导致兼容问题
可重现性：确保不同机器上运行环境一致
干净卸载：删除虚拟环境即可清除所有依赖

2. venv（标准库）

2.1 创建与激活

        
# 创建虚拟环境（Python 3.3+ 内置）
python -m venv myenv

# 激活虚拟环境
# macOS / Linux
source myenv/bin/activate

# Windows (CMD)
myenv\Scripts\activate.bat

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

# 退出虚拟环境
deactivate

2.2 目录结构

myenv/
├── bin/              ← macOS/Linux（Windows 为 Scripts/）
│   ├── activate      ← 激活脚本
│   ├── pip           ← 包管理器
│   └── python        ← Python 解释器
├── lib/
│   └── python3.11/
│       └── site-packages/  ← 安装的第三方包
├── include/          ← C 头文件
└── pyvenv.cfg        ← 配置文件

2.3 常用操作

        
        
        
    
# 查看当前虚拟环境的 Python 路径
which python
# /path/to/myenv/bin/python

# 查看已安装的包
pip list

# 安装包
pip install requests

# 安装指定版本
pip install django==4.2

# 升级包
pip install --upgrade requests

# 卸载包
pip uninstall requests

# 导出依赖
pip freeze > requirements.txt

# 从文件安装依赖
pip install -r requirements.txt

3. requirements.txt

3.1 基本格式

        
        
        
    
# requirements.txt
# 直接指定版本
Django==4.2.7

# 版本范围
requests>=2.25.0,<3.0.0

# 最小版本
celery>=5.0.0

# 不指定版本（不推荐）
flask

# 从 Git 安装
# git+https://github.com/user/repo.git@branch#egg=package

# 从本地路径安装
# ./my-local-package

# 包含额外依赖
uvicorn[standard]==0.24.0

3.2 分层管理

        
        
        
    
# requirements.txt - 生产环境
-r requirements/base.txt
gunicorn==21.2.0
psycopg2-binary==2.9.9
whitenoise==6.6.0

# requirements/base.txt - 基础依赖
Django==4.2.7
djangorestframework==3.14.0
python-dotenv==1.0.0

# requirements/dev.txt - 开发环境
-r requirements.txt
pytest==7.4.3
pytest-django==4.7.0
flake8==6.1.0
black==23.11.0

        
# 安装开发依赖
pip install -r requirements/dev.txt

# 安装生产依赖
pip install -r requirements.txt

4. pip 高级用法

4.1 配置文件

        
        
        
    
# pip.ini (Windows: %APPDATA%\pip\pip.ini)
# pip.conf (macOS/Linux: ~/.pip/pip.conf 或 ~/.config/pip/pip.conf)

[global]
# 使用国内镜像源
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
# 超时设置
timeout = 120
# 信任主机
trusted-host = pypi.tuna.tsinghua.edu.cn

[install]
# 不缓存下载
no-cache-dir = true

4.2 常用镜像源

        
# 临时使用镜像
pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple

# 国内常用镜像
# 清华:    https://pypi.tuna.tsinghua.edu.cn/simple
# 阿里云:  https://mirrors.aliyun.com/pypi/simple
# 中科大:  https://pypi.mirrors.ustc.edu.cn/simple
# 腾讯云:  https://mirrors.cloud.tencent.com/pypi/simple

4.3 其他实用命令

        
# 查看包信息
pip show django

# 查看过期的包
pip list --outdated

# 下载包（不安装）
pip download django -d ./packages/

# 离线安装
pip install --no-index --find-links=./packages/ django

# 检查依赖冲突
pip check

# 升级所有包（谨慎使用）
pip list --outdated --format=freeze | grep -v '^\-e' | cut -d = -f 1 | xargs -n1 pip install -U

5. Poetry（现代包管理）

5.1 安装与初始化

        
# 安装 Poetry
curl -sSL https://install.python-poetry.org | python3 -

# 或通过 pip
pip install poetry

# 初始化项目
poetry init

# 或从现有项目创建
poetry new my-project

5.2 项目结构

my-project/
├── pyproject.toml       ← 项目配置和依赖
├── poetry.lock          ← 锁定文件（精确版本）
├── README.md
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py

5.3 pyproject.toml

        
        
        
    
[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "A sample project"
authors = ["Your Name <you@example.com>"]
readme = "README.md"
packages = [{include = "my_project"}]

[tool.poetry.dependencies]
python = "^3.11"
django = "^4.2"
requests = "^2.31"
psycopg2-binary = "^2.9"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4"
black = "^23.11"
flake8 = "^6.1"

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

5.4 常用命令

        
        
        
    
# 安装依赖（自动创建虚拟环境）
poetry install

# 仅安装生产依赖（不含 dev 组）
poetry install --without dev

# 添加依赖
poetry add requests
poetry add "django>=4.2,<5.0"

# 添加开发依赖
poetry add pytest --group dev

# 移除依赖
poetry remove requests

# 更新依赖
poetry update
poetry update requests  # 仅更新某个包

# 查看依赖树
poetry show --tree

# 在虚拟环境中运行命令
poetry run python script.py
poetry run pytest

# 激活虚拟环境
poetry shell

# 构建包
poetry build

# 发布到 PyPI
poetry publish

6. uv（超快包管理器）

6.1 安装与基本使用

        
# 安装 uv（Rust 编写，极快）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境
uv venv

# 激活
source .venv/bin/activate

# 安装包（比 pip 快 10-100 倍）
uv pip install requests
uv pip install -r requirements.txt

# 从 pyproject.toml 同步
uv sync

6.2 项目管理

        
# 初始化项目
uv init my-project

# 添加依赖
uv add django
uv add pytest --dev

# 运行命令
uv run python script.py
uv run pytest

# 锁定依赖
uv lock

7. conda（数据科学环境）

7.1 基本操作

        
        
        
    
# 创建环境
conda create -n myenv python=3.11

# 激活环境
conda activate myenv

# 退出环境
conda deactivate

# 安装包
conda install numpy pandas scikit-learn

# 从 conda-forge 安装
conda install -c conda-forge django

# 列出环境
conda env list

# 导出环境
conda env export > environment.yml

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

# 删除环境
conda env remove -n myenv

7.2 environment.yml

        
        
        
    
name: myenv
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.11
  - numpy=1.24
  - pandas=2.0
  - scikit-learn
  - pip
  - pip:
    - django==4.2
    - djangorestframework

8. 工具对比

工具	速度	功能	适用场景
venv + pip	标准	基础	通用、学习
Poetry	快	全功能（构建/发布）	库开发、中大型项目
uv	极快	兼容 pip	追求速度的项目
pipenv	中等	全功能	中型项目
conda	慢	科学计算生态	数据科学、ML

选型建议

场景？
├── 学习 / 简单项目 → venv + pip
├── 库 / 包开发     → Poetry
├── 追求极速        → uv
├── 数据科学 / ML   → conda
└── 企业级项目      → Poetry 或 uv

9. .gitignore 配置

# .gitignore
# 虚拟环境
myenv/
.venv/
venv/
env/

# Python
__pycache__/
*.py[cod]
*$py.class
*.so

# 分发/打包
build/
dist/
*.egg-info/
*.egg

# 测试
.pytest_cache/
.coverage
htmlcov/

# IDE
.vscode/
.idea/
*.swp

# 环境变量
.env
.env.local

# 不忽略
!requirements.txt
!pyproject.toml

10. 最佳实践

        
        
        
    
"""
项目依赖管理最佳实践

1. 锁定版本
   - 生产环境使用精确版本 (==)
   - 开发环境可使用范围版本 (>=)

2. 分层管理
   - requirements/base.txt   基础依赖
   - requirements/dev.txt    开发工具
   - requirements/prod.txt   生产依赖

3. 使用锁文件
   - poetry.lock / uv.lock 确保可重现

4. 定期更新
   - 检查安全更新
   - 逐步升级大版本

5. CI/CD 集成
   - 自动安装依赖
   - 运行 pip check 验证
   - 使用锁文件确保一致性
"""

11. 小结

概念	工具	要点
虚拟环境	venv / conda	隔离项目依赖
包安装	pip / uv	安装第三方库
依赖声明	requirements.txt / pyproject.toml	记录依赖
版本锁定	poetry.lock / uv.lock	确保可重现
现代管理	Poetry / uv	全功能工具链

12. 练习题

使用 venv 创建虚拟环境，安装 Django 并导出 requirements.txt。
使用 Poetry 创建一个新项目，添加依赖并生成锁文件。
对比 pip 和 uv 安装同一组依赖的速度差异。
为你的项目设计分层 requirements 文件结构。

下节预告：我们将学习 pytest 测试框架，掌握编写高质量单元测试的方法。