【产出】 > 每个 Python 项目用独立的虚拟环境,在 Windows、macOS、Linux 上正确地创建、激活、安装依赖,用 requirements.txt 让别人一条命令复现环境,不再出现"在我电脑上能跑"的问题。
【版本】 > 按 Python 官方文档
venv模块编写,适用于 Python 3.8 及以上;3.13 起的新行为文中单独标出。
一、为什么每个项目都要虚拟环境
所有项目共用一个全局 Python 时,A 项目要 numpy 1.x、B 项目要 numpy 2.x,装了一个另一个就坏。虚拟环境给每个项目一个独立的目录,里面有自己的解释器链接和第三方包,互不影响。
官方文档对虚拟环境的定位:
- 放在项目目录下,约定俗成命名为
.venv或venv。 - 不提交到 Git 等版本库。
- 随时可以删掉重建,不要把项目代码放进环境目录。
- 不能移动或复制。需要换位置时,在新位置重新创建,再删掉旧的。
二、创建
在项目根目录执行:
python -m venv .venv
Windows 上如果 python 指向的不是你想要的版本,可以用 Python 启动器指定,例如 py -3.12 -m venv .venv。
【提示】 > 从 Python 3.13 开始,
venv会在环境目录里自动生成一个.gitignore,Git 默认就会忽略它。不需要时可以加--without-scm-ignore-files。旧版本请自己在项目的.gitignore里加一行.venv/。
三、激活与退出
| 系统 / Shell | 激活命令 |
|---|---|
| Linux / macOS(bash、zsh) | source .venv/bin/activate |
| fish | source .venv/bin/activate.fish |
| Windows cmd | .venv\Scripts\activate.bat |
| Windows PowerShell | .venv\Scripts\Activate.ps1 |
激活后命令行前面会出现 (.venv)。退出输入 deactivate。
PowerShell 提示"禁止运行脚本":官方给出的解决方法是为当前用户放开执行策略:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
官方还说明:激活不是必须的。直接用环境里解释器的完整路径也可以,写脚本、配计划任务时这样更可靠:
.venv/bin/python main.py # Linux / macOS
.venv\Scripts\python.exe main.py # Windows
四、安装依赖
在激活的环境里,pip 会自动把包装进这个环境,不会碰全局 Python:
python -m pip install --upgrade pip
python -m pip install requests numpy
用 python -m pip 而不是直接 pip,可以确保用的是当前环境里的 pip。
五、requirements.txt:让别人复现环境
导出当前环境里装的包和版本:
python -m pip freeze > requirements.txt
别人拿到项目后:
python -m venv .venv
source .venv/bin/activate # Windows 换成对应的激活命令
python -m pip install -r requirements.txt
【注意】 >
pip freeze会把所有间接依赖也列进去,并且锁定精确版本。适合部署和复现,但手工维护起来比较乱。一个常见做法是:手写一份只列直接依赖的requirements.in,用工具(如 pip-tools)生成锁定版本的requirements.txt。
六、常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
装了包,运行时却报 ModuleNotFoundError | 运行时用的不是环境里的 Python | 先激活环境;在 IDE 里把解释器选成 .venv 里的那个 |
| 把项目文件夹挪了位置后,环境里的命令报错 | 环境里的脚本写死了旧的绝对路径,官方明确说明环境不可移动 | 删掉 .venv,在新位置重新创建并安装依赖 |
| VS Code 不认环境 | 没有选中解释器 | Ctrl+Shift+P → Python: Select Interpreter → 选 .venv |
系统提示 externally-managed-environment,不让 pip 安装 | 新版 Linux 发行版禁止往系统 Python 里装包 | 这正说明应该用虚拟环境;不要加 --break-system-packages 硬装 |
七、项目目录建议
my-project/
├── .venv/ # 虚拟环境,不提交
├── .gitignore # 包含 .venv/
├── requirements.txt # 提交
├── src/
└── README.md # 写清楚:创建环境 + pip install -r requirements.txt
参考资料
- Python 官方文档:venv https://docs.python.org/3/library/venv.html
评价 (0)