DevNull 知识库

Appearance

19｜虚拟环境与依赖 ​

Python 项目经常依赖第三方库。不同项目需要的库版本不同，装到系统 Python 里会互相冲突。虚拟环境给每个项目独立的包安装空间，解决这个问题。

一、venv ​

Python 自带 venv 模块，无需额外安装：

bash
# 创建虚拟环境
python3 -m venv .venv

# 激活（Linux/macOS）
source .venv/bin/activate

# 激活（Windows PowerShell）
.venv\Scripts\Activate.ps1

激活后，命令行提示符前会出现 (.venv)，表示当前在虚拟环境中。此时 python 和 pip 指向虚拟环境里的版本，不是系统的。

bash
which python        # 显示 .venv/bin/python
pip install requests

退出虚拟环境：

bash
deactivate

二、pip ​

pip 是 Python 的包管理器，从 PyPI（Python Package Index）下载和安装第三方库。

bash
pip install requests              # 安装最新版
pip install requests==2.28.1     # 安装指定版本
pip install requests>=2.28,<3.0  # 安装版本范围内的最新版
pip install -r requirements.txt   # 从文件批量安装

查看已安装包：

bash
pip list
pip show requests                 # 查看单个包的详细信息

卸载：

bash
pip uninstall requests

三、requirements.txt ​

记录项目依赖的标准方式是 requirements.txt：

text
requests>=2.28,<3.0
pyyaml==6.0.1
paramiko

每行一个包，可以指定版本约束：

  • ==：精确版本
  • >=：最低版本
  • <=：最高版本
  • ~=：兼容版本（如 ~=2.28.0 表示 2.28.0 到 2.29.0 之间）

生成当前环境的依赖列表：

bash
pip freeze > requirements.txt

pip freeze 输出所有已安装包（包括间接依赖）的精确版本。在新环境恢复：

bash
pip install -r requirements.txt

四、uv ​

uv 是用 Rust 编写的新一代 Python 包管理器，兼容 pip 和 venv，但速度更快、功能更整合。

安装 uv：

bash
curl -LsSf https://astral.sh/uv/install.sh | sh

创建项目并管理依赖：

bash
uv init myproject
cd myproject

uv add requests          # 安装并写入 pyproject.toml
uv add requests==2.28.1  # 安装指定版本
uv remove requests       # 卸载

uv sync                  # 按 pyproject.toml 和 uv.lock 恢复环境
uv run python script.py  # 用项目环境执行脚本

uv 把虚拟环境、依赖安装、锁文件管理整合到一起。uv run 自动使用项目环境，不需要手动 source .venv/bin/activate。

pyproject.toml 是 modern Python 项目的标准配置文件：

toml
[project]
name = "myproject"
version = "0.1.0"
dependencies = [
    "requests>=2.28",
]

uv.lock 记录精确版本，保证不同机器上安装的依赖完全一致。

五、依赖管理策略 ​

直接依赖 vs 间接依赖 ​

直接依赖：项目代码里直接 import 的包。间接依赖：直接依赖所依赖的包。

requirements.txt 通常只记录直接依赖，让 pip 自己解析间接依赖。pip freeze 记录全部（包括间接依赖），文件很长但环境完全一致。

两种策略各有适用场景：

  • 只记直接依赖：requirements.txt 简洁，升级更灵活
  • 记全部依赖：环境完全一致，但升级时需要手动处理

开发依赖 ​

只在开发和测试时用的包（如测试框架、代码格式化工具），不应该出现在生产环境：

toml
[project.optional-dependencies]
dev = ["pytest", "black", "ruff"]
bash
pip install -e ".[dev]"   # 安装项目 + 开发依赖

六、常见问题 ​

问题原因解决
ModuleNotFoundError包装到了别的环境确认激活了正确的虚拟环境，which python 检查路径
权限错误用系统 pip 安装改用虚拟环境，或加 --user
版本冲突不同包依赖同一个包的不同版本用虚拟环境隔离，或升级/降级相关包
编译失败包需要 C 编译器安装 python3-dev/build-essential，或找预编译的 wheel

七、配置国内镜像 ​

PyPI 下载慢时，配置国内镜像：

bash
# pip 全局配置
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# uv 临时使用
uv add requests --default-index https://pypi.tuna.tsinghua.edu.cn/simple

# uv 环境变量
export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple

常用镜像源：清华、阿里云、腾讯云、华为云。https 镜像通常不需要额外配置 trusted-host。

记忆锚点：python3 -m venv .venv 创建虚拟环境；source .venv/bin/activate 激活，deactivate 退出；pip install 安装，pip freeze 导出；requirements.txt 记录依赖，pip install -r 恢复；uv 整合环境创建、依赖安装和锁文件；pyproject.toml 是现代项目的标准配置；直接依赖和间接依赖分开管理；国内镜像加速下载。