用venv隔离跑OCR示例：创建、激活、对照README钉依赖再装

准备工作

• 已安装Python 3.12+（与Unlimited-OCR README测试口径接近更佳）。[1][2]

• 官方venv文档：https://docs.python.org/3/library/venv.html 。[1]

操作步骤

1、创建虚拟环境

做什么：在项目目录执行python3 -m venv .venv。
为什么：把torch/transformers钉在隔离环境，避免污染系统Python。[1]
如何确认：目录下出现.venv/，其中有bin/python或Scripts\python.exe。

2、激活并确认解释器路径

做什么：macOS/Linux执行source .venv/bin/activate；Windows用.venv\Scripts\activate。然后which python / where python。
为什么：装错到系统Python是最常见翻车。[1]
如何确认：路径指向项目里的.venv。

3、按第三方项目README安装钉死版本

做什么：例如按Unlimited-OCR列出的版本安装torch与transformers，再装项目自身依赖。[2]
为什么：多模态trust_remote_code模型对版本敏感。[2]
如何确认：python -c "import torch; print(torch.__version__, torch.cuda.is_available())"符合预期。

4、退出与重建

做什么：deactivate退出；环境坏了就删.venv重建，不要混用pip全局包。
为什么：venv可丢弃是它的优点。[1]
如何确认：deactivate后which python回到系统路径。

5、把依赖冻结成requirements，便于同事复现

做什么：环境验证通过后执行pip freeze > requirements-lock.txt（或按项目推荐用uv/poetry导出）。
为什么：只写“按README安装”无法锁定传递依赖。[1]
如何确认：新venv里pip install -r requirements-lock.txt后，关键import成功。

6、GPU不可用时显式失败，而不是静默CPU硬撑

做什么：在入口脚本加assert torch.cuda.is_available(), "需要CUDA"（或你的项目等价检查）。
为什么：Unlimited-OCR类模型在CPU上可能极慢或直接不支持，静默回落会浪费时间。[2]
如何确认：在无GPU机器上脚本快速报错退出。

注意事项

• GPU驱动与CUDA不在venv里解决，需系统级就绪。[2]

• 不要把.venv提交进git。

常见问题

• activate后pip仍指向系统？ 检查是否用了sudo pip或IDE选错解释器；以which python/which pip为准。[1]

• torch安装CPU轮子？ 按PyTorch官网CUDA轮子索引安装，再回到项目README版本约束。[2]

• 删了.venv但终端还显示venv前缀？ 执行deactivate或重开终端。

做完后，你应有一个可丢弃的.venv、一份锁定依赖，以及在无GPU机器上会快速失败的入口检查。

说明：venv 步骤以 Python 官方文档为准；OCR 依赖版本以 baidu/Unlimited-OCR README 于 2026-10-24 所列为准。虚拟环境不解决 NVIDIA 驱动与 CUDA 安装问题，需在系统层先就绪再进 venv 装框架轮子。

来源

[1] venv — Creation of virtual environments，Python Docs，核对于2026-10-24。
[2] baidu/Unlimited-OCR README 依赖列表，核对于2026-10-24。

#Python #venv #教程 #依赖隔离 #OCR