Python venv与requirements.txt依赖隔离

脚本专家

在 Python 项目里直接执行 pip install requests 看似省事，但项目一多就容易出现依赖冲突：A 项目需要 requests==2.28.0，B 项目需要 requests==2.32.0，如果都装进系统 Python，后续排查版本问题会很麻烦。Python 标准库自带的 venv 可以为每个项目创建轻量级虚拟环境，环境内有独立的 Python 包目录、pip 和激活脚本，项目之间互不影响。

一、venv 的作用与项目结构

venv 不需要额外安装第三方包。它会在项目目录下生成一个独立的小环境，项目 A 安装的包不会影响项目 B，项目 B 升级依赖也不会破坏项目 A。

先创建演示项目：

2. mkdir python-venv-demo
3. cd python-venv-demo

复制代码

推荐的项目结构如下：

python-venv-demo/
├── .venv/
├── main.py
└── requirements.txt

其中 .venv 是虚拟环境目录，main.py 是业务代码，requirements.txt 用于记录依赖。.venv 通常不提交到 Git，因为它可以根据 requirements.txt 重新生成。

二、创建并激活虚拟环境

macOS 或 Linux 下执行：

2. python3 -m venv .venv

复制代码

Windows 下执行：

2. py -m venv .venv

复制代码

执行完成后，项目目录下会多出 .venv 文件夹。

激活虚拟环境：

macOS 或 Linux：

2. source .venv/bin/activate

复制代码

Windows PowerShell：

2. .\.venv\Scripts\Activate.ps1

复制代码

Windows CMD：

2. .venv\Scripts\activate.bat

复制代码

激活成功后，终端提示符前通常会出现 (.venv)，表示当前 shell 已进入该项目的虚拟环境。

三、安装依赖并验证

激活环境后，建议用下面这种写法安装依赖：

2. python -m pip install requests

复制代码

使用 python -m pip 而不是裸 pip install，目的是明确调用当前 Python 解释器对应的 pip，减少多个 Python 版本共存时装错环境的问题。

安装完成后，写一个简单的 main.py 验证：

2. import requests
4. response = requests.get("https://httpbin.org/get", timeout=5)
5. print(response.status_code)
6. print(response.json()["url"])

复制代码

运行：

2. python main.py

复制代码

如果输出 200 和请求地址，说明依赖安装和代码运行都正常。

四、生成与使用 requirements.txt

开发过程中安装的依赖需要记录，便于别人或服务器复现环境。生成依赖文件：

2. python -m pip freeze > requirements.txt

复制代码

查看内容：

2. cat requirements.txt

复制代码

可能得到类似结果：

2. certifi==2025.8.3
3. charset-normalizer==3.4.3
4. idna==3.10
5. requests==2.32.4
6. urllib3==2.5.0

复制代码

这个文件应提交到 Git 仓库。其他人拿到项目后，可以按相同依赖版本安装。

换电脑或部署到服务器时，重建环境流程如下（macOS/Linux）：

2. python3 -m venv .venv
3. source .venv/bin/activate
4. python -m pip install -r requirements.txt

复制代码

Windows PowerShell 对应写法：

2. py -m venv .venv
3. .\.venv\Scripts\Activate.ps1
4. python -m pip install -r requirements.txt

复制代码

这样不需要拷贝整个 .venv 目录，只保留项目代码和 requirements.txt 即可。

五、配置 .gitignore 与退出虚拟环境

虚拟环境目录不要提交到 Git，建议在项目根目录创建 .gitignore：

2. .venv/
3. __pycache__/
4. *.pyc
5. .env

复制代码

.venv/ 可以重新创建；__pycache__/ 和 *.pyc 是 Python 运行过程中生成的缓存文件；.env 通常存放本地环境变量，也不建议提交。

退出当前虚拟环境执行：

2. deactivate

复制代码

退出后，终端前面的 (.venv) 会消失。

六、常见问题排查

1. pip 安装到了系统环境

先确认是否已经激活虚拟环境，再执行：

2. which python
3. which pip

复制代码

Windows 中可以使用：

2. where python
3. where pip

复制代码

如果路径里包含 .venv，说明当前使用的是项目虚拟环境。

2. PowerShell 不允许执行激活脚本

Windows 上可能遇到执行策略限制，可以临时执行：

2. Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

复制代码

然后重新打开 PowerShell，再激活虚拟环境。

3. requirements.txt 里依赖太多

pip freeze 会把当前环境里所有包都写进去，包括间接依赖。小项目可以接受。如果项目复杂，可以考虑使用 Poetry、uv 或 pip-tools 做更细的依赖管理。

七、推荐工作流

日常开发可以按这个顺序操作：

2. mkdir my-project
3. cd my-project
4. python3 -m venv .venv
5. source .venv/bin/activate
6. python -m pip install requests
7. python -m pip freeze > requirements.txt

复制代码

提交代码时，提交 main.py、requirements.txt、.gitignore，不要提交 .venv。

总结

Python 项目依赖管理的核心是隔离和可复现。venv 负责隔离环境，requirements.txt 负责记录依赖版本。对于普通 Python 项目，先掌握 python -m venv .venv、source .venv/bin/activate、python -m pip install -r requirements.txt 这几个命令，就已经能解决大多数本地开发和服务器部署中的依赖问题。