刚接触 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 项目。