Python 虚拟环境与依赖管理

一个 Python 项目应该拥有独立环境。把依赖直接安装进系统 Python，容易造成版本冲突，也不利于部署和复现。

创建与激活环境#

1
python -m venv .venv
2

3
# Linux / macOS
4
source .venv/bin/activate
5

6
# Windows PowerShell
7
.venv\Scripts\Activate.ps1

确认环境：

1
python -c "import sys; print(sys.executable)"
2
python -m pip --version

退出环境：

1
deactivate

pip 的常用操作#

1
python -m pip install requests
2
python -m pip install "django>=5,<6"
3
python -m pip uninstall requests
4
python -m pip list
5
python -m pip show requests
6
python -m pip check

pip check 可以检查已安装包之间是否存在依赖冲突。

requirements.txt#

记录当前环境完整版本：

1
python -m pip freeze > requirements.txt

恢复环境：

1
python -m pip install -r requirements.txt

对应用项目来说，完整锁定版本有利于复现。对库项目来说，不宜把所有间接依赖都写死，应在项目元数据中声明合理的版本范围。

pyproject.toml#

现代 Python 项目通常使用 pyproject.toml 描述项目和直接依赖：

1
[build-system]
2
requires = ["setuptools>=75"]
3
build-backend = "setuptools.build_meta"
4

5
[project]
6
name = "example-app"
7
version = "0.1.0"
8
requires-python = ">=3.12"
9
dependencies = [
10
  "requests>=2.32,<3",
11
]

开发模式安装：

1
python -m pip install -e .

这样修改源码后不需要反复重新安装。

依赖升级策略#

不要一次性无条件升级所有包。更稳妥的流程是：

查看过期包；
阅读目标版本变更说明；
单独升级一个直接依赖；
运行测试；
更新依赖快照。

1
python -m pip list --outdated
2
python -m pip install --upgrade requests
3
python -m pip check

缓存与镜像排查#

1
python -m pip cache dir
2
python -m pip cache purge
3
python -m pip config list

网络异常时先检查代理、证书和 pip 配置，不要随意关闭 TLS 校验。

不要提交虚拟环境#

.gitignore 中加入：

1
.venv/
2
__pycache__/
3
*.py[cod]
4
.pytest_cache/

虚拟环境是可生成产物，项目仓库应保存依赖声明，而不是保存环境目录。

开发动态