Python 虚拟环境 venv 入门：从依赖隔离到日常协作

一、为什么需要虚拟环境

同一个团队里经常出现这样的场景：项目 A 依赖 requests 2.19，项目 B 需要 requests 2.31，两个版本很难同时装在同一个解释器的 site-packages 里。把包都装到系统全局短期省事，长期必然互相污染，在 CI 镜像或服务器上还可能牵连系统工具自带的 Python 包。虚拟环境的意义，就是给每个项目一套独立的解释器目录和独立的第三方包集合，让依赖彼此隔离、可复现、可随时丢弃重建。

二、venv 是什么，为什么优先选它

从 Python 3.3 开始，标准库自带 venv 模块，无需额外安装就能创建轻量环境。它通过目录里的 pyvenv.cfg 记录所指向的基础解释器，并在 bin（Windows 下是 Scripts）中放置解释器副本与激活脚本。相比第三方工具，venv 的优势是零额外依赖、跨平台行为一致、能被主流 IDE 和 CI 镜像直接识别。如果还需要管理多个版本的解释器本身，可以在 venv 之上再引入 pyenv 一类工具，两者职责不同，并不冲突。

三、创建与激活

激活环境：

python3 -m venv .venv
source .venv/bin/activate

Windows 用户在命令提示符下执行 .venv\Scripts\activate.bat，在 PowerShell 下执行 .venv\Scripts\Activate.ps1。激活后命令行提示符前会出现环境名，which python 指向 .venv 内的解释器，此时 pip install 安装的包只会落在这个目录里，退出用 deactivate。一个常见的坑是：PowerShell 默认的执行策略可能禁止运行脚本，激活脚本静默失败，看起来就像装了包却 import 不到，需要以 CurrentUser 范围放开一次执行策略。

四、依赖固化与环境复现

pip freeze 加输出重定向到 requirements.txt 能导出当前环境的精确版本，但更适合协作的做法是把直接依赖写进 requirements.txt，再用 pip install -r requirements.txt 复现环境。需要区分的是：pip freeze 会把传递依赖一并锁定，版本升级时容易整体冲突；只想保留顶层依赖时，用 pip list --not-required 辅助筛选更清晰。对安全性要求较高的生产构建，可以再加上哈希校验，执行 pip install --require-hashes -r requirements.txt，防止镜像被替换后引入不受信任的包。

五、日常实践建议

1. 项目根目录放 .venv，并把 .venv/ 写进 .gitignore，永远不要提交虚拟环境本身。
2. 当有人提出要重装系统 Python 才能装这个包时先停一下，八成是该为项目建虚拟环境了。
3. CI 里缓存的应当是 pip 的下载缓存目录，而不是整个 .venv，否则换一台机器后路径前缀失效会带来诡异报错。
4. 排查 import 异常时，先用 python -c 打印 sys.executable，确认正在使用的到底是不是环境内的解释器。

六、小结

venv 解决的不是能不能装包，而是多个项目能否长期共存。它足够小、足够标准，也因此成为多数 Python 工程实践的默认起点。把创建、激活、锁定、复现这四步固化成脚本或 Makefile 目标之后，一个新项目从零到可运行的时间可以压缩到几十秒。