刚接触 Python 的时候,我习惯把所有包装进全局环境,直到某一天两个项目依赖了同一个库的不同版本, 才意识到问题的严重性。虚拟环境就是用来解决这类问题的:让每个项目拥有独立的解释器和依赖目录, 互不干扰。

为什么需要虚拟环境

默认情况下,pip install 会把包装到 Python 安装目录的 site-packages 下。 如果同时维护 A、B 两个项目,A 需要 Django 4.2,B 需要 Django 5.0, 全局环境里只能保留一个版本,必然有一个项目跑不起来。

虚拟环境的做法是:为每个项目复制一份轻量的 Python 运行目录,激活后所有 pip 安装、 python 执行都只作用于这个目录。项目结束后删掉整个文件夹即可,不污染系统。

用 venv 创建虚拟环境

venv 是 Python 3.3 起内置的模块,不需要额外安装,这也是我推荐它作为默认方案的原因。 在项目根目录执行:

python -m venv .venv

命令会在当前目录生成一个名为 .venv 的文件夹。名字可以随意,业界常见的有 .venv、venv、env,我一般用 .venv, 这样编辑器和其他工具更容易自动识别。

激活与退出

不同操作系统的激活命令不一样:

# Windows(PowerShell)
.venv\Scripts\Activate.ps1

# Windows(CMD)
.venv\Scripts\activate.bat

# macOS / Linux
source .venv/bin/activate

激活成功后,命令行提示符前面通常会出现 (.venv) 字样。此时执行 python -c "import sys; print(sys.prefix)",输出的路径应该指向项目里的 .venv,而不是系统 Python 目录。

退出虚拟环境很简单:

deactivate

在 Windows 上如果提示“无法加载文件,因为在此系统上禁止运行脚本”, 需要先以管理员身份执行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, 或者改用 CMD 的 activate.bat。

管理依赖:requirements.txt

虚拟环境解决了“隔离”,接下来要解决“复现”。最通用的约定是把依赖写进 requirements.txt,别人拿到项目后一条命令就能装好。

安装依赖:

python -m pip install -r requirements.txt

根据当前环境导出依赖:

python -m pip freeze > requirements.txt

导出的内容形如:

Django==5.0.6
asgiref==3.8.1
sqlparse==0.5.0
tzdata==2024.1

这里有个细节:freeze 会把所有间接依赖也列出来,并且锁定精确版本。 对于需要长期部署的项目,这是好事,能保证线上和本地装出来的东西完全一致; 但对于要发布给别人使用的库,通常只希望声明直接依赖,这时更推荐手写依赖文件, 或者用 pip-tools 之类的工具分层管理。

几个常用命令

命令作用
python -m pip install -U pip升级 pip 自身
python -m pip list查看当前环境已安装的包
python -m pip show django查看某个包的版本、位置和依赖
python -m pip uninstall 包名卸载包
python -m pip install -i 镜像源 包名临时指定安装源

国内网络环境下,可以临时使用镜像源加速,例如 python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple requests。 如果要长期生效,可以写进 pip.ini(Windows)或 ~/.pip/pip.conf(Linux/macOS)。

常见问题

1. 装了包但导入失败

九成是因为编辑器或终端没有激活对应的虚拟环境。先用 where python(Windows)或 which python(macOS/Linux) 确认解释器路径,再检查 pip -V 是否指向同一个环境。 如果 pip 和 python 来自不同环境,装进去的包自然找不到。

2. 把 .venv 提交到了 Git

虚拟环境目录包含大量平台相关的二进制文件,既臃肿又不可移植。项目初始化时就应该在 .gitignore 里加上:

.venv/
__pycache__/
*.py[cod]
.env

3. requirements.txt 没有锁版本

只写 Django 而不写版本号,半年后重新部署很可能因为上游发布新版本而行为改变。 生产项目建议锁定到次版本,例如 Django>=5.0,<5.1,或者直接用 == 精确锁定。

小结

一个健康的 Python 项目,起点通常就是这三件事:创建 .venv、写好 .gitignore、维护 requirements.txt。它们看起来琐碎, 但能避免后续大量的“在我机器上是好的”问题。

下一篇文章会在这个基础上,用 Django 搭起一个真正能访问的 Web 项目。