Python 虚拟环境与依赖管理入门：venv + pip + requirements.txt 实操

刚学 Python 时，很多人都是直接在系统里 pip install，装着装着就乱了：A 项目要 requests 2.x，B 项目要 1.x；升级一个库，另一个项目跟着报错；换一台电脑重装，又想不起当初装了哪些包。问题往往不在 pip，而在没有做环境隔离。venv 是 Python 3.3 起自带的虚拟环境工具，作用就是给每个项目一个独立的“小房间”，包互不干扰，换环境也能一键还原。

一、为什么要用虚拟环境

系统 Python 是公共环境，所有项目共用同一套包。项目一多，依赖版本必然打架。虚拟环境则把解释器、pip 和第三方包复制一份，放在项目目录里，只对当前项目生效。删除它也不会影响系统 Python，重建也很容易。

一个简单的判断标准：如果一个项目将来要给别人用、要部署到服务器，或者要长期维护，就值得单独建虚拟环境。临时写几行脚本做实验，可以不用讲究；一旦开始写真正的项目，先建环境再装包，顺序不要反。

二、三步创建一个虚拟环境

先进入项目目录，然后创建名为 .venv 的环境：

cd my-project
python3 -m venv .venv

Windows 上命令基本一样，把 python3 换成 py 或 python 即可。创建完成后，项目里会多出一个 .venv 文件夹，里面有独立的 Python 解释器和 pip。

接着激活它。macOS 和 Linux 用：

source .venv/bin/activate

Windows 用：

.venv\Scripts\activate

激活成功后，命令行前面会出现 (.venv) 这样的前缀。可以用 which python 或 python --version 确认当前用的是环境里的解释器，再用 pip list 看看初始只有 pip、setuptools 等少数基础包。

用完之后输入 deactivate 退出，提示符恢复正常。环境本身还在，下次再激活就能继续用。

三、用 pip 管理依赖

激活环境后，再安装项目需要的包，例如：

pip install requests
pip install flask==3.0.0

pip 默认从 PyPI 下载，网络慢时可以临时换国内源，例如加上 -i https://pypi.tuna.tsinghua.edu.cn/simple。需要升级某个包时用 pip install -U 包名，卸载用 pip uninstall 包名。

安装前先想清楚：这个包是项目真正需要的，还是顺手装来试试的？试用性质的包不要急着写进依赖清单，否则清单会越积越乱。

四、用 requirements.txt 固化依赖

依赖装好后，把当前环境的包列表导出成文件：

pip freeze > requirements.txt

这个文件就是项目的“配料表”，建议提交到代码仓库。别人拿到项目后，只需两步就能还原出同样的环境：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

这里有个常见误区：pip freeze 导出的是全部已装包，包括某个包顺带装上的依赖，版本也会被完全锁定。好处是还原结果稳定，坏处是清单偏长、升级不方便。小型项目直接用它完全没问题；依赖复杂时，可以手写一份只列直接依赖的 requirements.txt，例如只写 requests>=2.31，再配合定期检查升级。

五、几个容易踩的坑

第一，忘记激活就装包。没有 (.venv) 前缀时 pip install 装的是系统环境，项目运行时却找不到包。装包前先看一眼提示符，养成习惯。

第二，把 .venv 提交到 Git。虚拟环境体积大、且与操作系统有关，不应该进仓库。在 .gitignore 里加一行 .venv/ 就能避免。

第三，在项目里混用多个 Python。系统 Python、Homebrew 装的 Python、pyenv 管理的版本各不相同，创建环境时最好先确认 python3 --version，团队里统一一个版本，少很多奇怪问题。

第四，用 sudo pip install。系统级安装容易破坏系统自带的 Python 工具，遇到权限问题时，正确的方向是检查是不是忘激活虚拟环境，而不是加 sudo。

六、一个可照抄的工作流

新建项目时按这个顺序走，基本不会出错：创建项目目录、python3 -m venv .venv、激活环境、pip install 需要的包、pip freeze > requirements.txt、把 .venv 写进 .gitignore。换电脑或换同事接手时，则是反向操作：克隆代码、创建并激活环境、pip install -r requirements.txt、运行项目验证。

虚拟环境本身没有魔法，它只是把“这个项目用哪些包、什么版本”这件事变得明确、可重复。把这套流程跑通一次，以后无论是写爬虫、做 Web 接口还是跑数据分析，环境问题都很少再成为拦路虎。