机器学习与深度学习 / 系统课时
使用虚拟环境管理依赖
使用虚拟环境管理依赖
这节把每个 TensorFlow 项目的 Python 解释器和第三方包隔离开,并把已验证的依赖版本记录下来。完成后,你可以在另一个空环境中按锁定文件重装依赖,并用 pip check 与解释器路径确认环境没有串包。
学习目标
- 使用标准库
venv为单个项目创建独立 Python 环境。 - 区分直接依赖文件与完整锁定文件,并按固定版本复现环境。
- 通过解释器路径、环境前缀和
pip check定位常见的环境错位。
创建并激活项目环境
推荐把虚拟环境放在项目根目录的 .venv。本课以 Python 3.12 为例;如果你的受支持解释器命令是 python3,可把示例中的 python3.12 原样替换为 python3。创建后必须确认当前解释器确实来自 .venv,不能只看终端提示符。
Linux 或 macOS:
python3.12 -m venv .venv
source .venv/bin/activate
python -c "import sys; print(sys.prefix != sys.base_prefix); print(sys.executable)"预期结果:第一行必须是 True,第二行路径应位于当前项目的 .venv/bin 下。
True
<PATH>/.venv/bin/pythonWindows PowerShell:
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.prefix != sys.base_prefix); print(sys.executable)"预期输出:
True
<PATH>\.venv\Scripts\python.exe如果第一行是 False,说明当前仍在使用系统解释器。此时不要安装依赖,先重新激活环境并再次检查。
固定直接依赖与完整锁定
项目应区分“我主动选择的包”和“安装器解析出的全部传递依赖”。例如本课程项目可以先用一个短的 requirements.txt 声明直接依赖:
tensorflow==2.21.0== 会把 TensorFlow 固定到 2.21.0,避免团队成员今天装 2.21、几个月后又自动装到不同主次版本。安装完成后再生成完整锁定文件:
python -m pip install -r requirements.txt
python -m pip freeze > requirements-lock.txt
python -m pip check预期结果:前两条命令的下载日志会因平台和缓存不同而变化,最后 pip check 必须报告依赖关系完整。
No broken requirements found.再确认锁定文件确实包含目标 TensorFlow 版本:
python -c "from pathlib import Path; lines=Path('requirements-lock.txt').read_text().splitlines(); print('tensorflow==2.21.0' in lines)"预期输出:
True不要手工删改 requirements-lock.txt 里的传递依赖;需要升级时先修改 requirements.txt,在一个干净环境里重新安装、测试,再重新生成锁定文件。
在干净环境验证可复现
“能在自己的 .venv 运行”还不足以证明依赖可复现。验收方法是在另一个空环境中仅依赖锁定文件安装一次。下面以 Linux/macOS 为例:
python3.12 -m venv .venv-repro
source .venv-repro/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-lock.txt
python -m pip check
python -c "import tensorflow as tf; print(tf.__version__)"预期结果:安装日志可以不同,但最后两项检查应得到依赖完整和指定 TensorFlow 版本。
No broken requirements found.
2.21.0Windows 的流程完全相同,只把激活命令替换为 .\.venv-repro\Scripts\Activate.ps1。验证结束后可执行 deactivate 离开环境,并删除 .venv-repro;真正项目使用的 .venv 也应加入 .gitignore,不要提交数百兆字节的本地环境目录。
.gitignore 至少包含:
.venv/
.venv-repro/这两个目录都可以随时由依赖文件重新创建,版本库只需要保存源码、requirements.txt 和经过验证的 requirements-lock.txt。
排查环境错位与依赖冲突
出现“明明安装了却 ModuleNotFoundError”时,最常见原因不是包不存在,而是运行代码的 Python 与安装包的 Python 不是同一个。先在出错的同一终端执行诊断:
python -c "import sys, tensorflow as tf; print(sys.executable); print(sys.prefix != sys.base_prefix); print(tf.__version__)"预期结果应同时满足:解释器位于项目 .venv、第二行是 True、版本与项目约定一致。
<PATH>/.venv/bin/python
True
2.21.0Windows 的第一行会是 <PATH>\.venv\Scripts\python.exe,判断标准不变。若导入失败到连这段命令都无法执行,就先运行 python -m pip --version,确认输出路径包含当前 .venv。
| 现象 | 常见根因 | 处理 |
|---|---|---|
| 已安装 TensorFlow 但导入失败 | pip 属于另一个 Python |
始终使用 python -m pip,不要混用裸 pip |
| IDE 能运行、终端不能运行 | IDE 与终端解释器不同 | 把两边都指向项目 .venv |
pip check 报版本冲突 |
手工升级了某个传递依赖 | 回到锁定文件重建环境,不在坏环境上继续打补丁 |
| 换电脑后安装失败 | Python 主次版本或平台不同 | 先统一 Python 版本,再重新解析并生成该平台的锁定文件 |
虚拟环境解决的是“项目之间不要共享同一组包”,锁定文件解决的是“同一项目尽量得到相同版本”。两者一起使用,才能把一次可运行的 TensorFlow 环境变成可重复创建的项目环境。