Python项目虚拟环境与依赖管理:venv / pip / requirements.txt实操教学

pip install 成功了，import 却报错。

现在彻底根治它，顺便解决另一个世纪难题——项目换台电脑就跑不起来。

太长不看版（给想快速上手的你）

一、先看三场“人间惨 案”（你大概率遇到过）

惨 案一：装了，但没完全装

你 pip install requests 提示成功，一运行还是 ModuleNotFoundError。

真相：你机器上有好几个Python，pip把包装进了你没在用的那个

惨 案二：升级一个包，搞坏了两个项目

项目A需要 requests==2.32，项目B依赖 requests==2.28。所有包都堆在同一个“全局”抽屉里，升级A的那一刻，B默默坏了。

惨 案三：换台电脑，项目报废

代码拷过去了，一跑全是 ModuleNotFoundError——你根本记不清装过哪些包、什么版本。

三个惨 案指向同一个病根：所有项目的包共用一个公共抽屉。解法就是给每个项目一间独立房间——虚拟环境（Virtual Environment）。

二、venv实操：给项目一间独立的房间

venv是Python官方自带的虚拟环境工具，不用装任何东西。

原理一句话：它把解释器和包安装目录单独复制一份放进项目文件夹，从此这个项目装什么、装哪个版本，都不影响别人。

标准四步（核心中的核心）

先在终端里 cd 到你的项目根目录，然后对照下表执行：

 “多版本共存”在这里用上了：py -3.13 -m venv venv 可以指定用哪个版本建房间。

激活成功的唯一标志

命令行提示符最前面多出 (venv) 前缀

# 激活前
C:\myproject>
# 激活后
(venv) C:\myproject>

看到 (venv)，说明你已经“进入房间”了。没看到？回到报错①自查。

验证：亲眼看 pip “搬家”

需要你留意 pip --version 末尾的 (python 3.13)，现在揭晓用处——激活前后各敲一次：

# 激活前：pip 属于全局
pip --version
# pip 25.x from C:\...\Python313\Lib\site-packages\pip (python 3.13)

# 激活后：pip 搬进了项目文件夹
pip --version
# pip 25.x from D:\myproject\venv\Lib\site-packages\pip (python 3.13)

路径从全局目录变成了项目里的 venv 目录——pip已经搬进这个房间，接下来它装的一切都只属于这个项目。惨 案一、二的解药，就是这一行路径的变化。

接回编辑器（重要！）

新建了venv，VSCode不会自动切换过去：

1. Ctrl+Shift+P → Python: Select Interpreter
2. 这次要选带 venv 路径的那一个（venv\Scripts\python.exe 或 ./venv/bin/python）
3. 选完右下角状态栏会显示 ('venv': venv) 

PyCharm新建项目时默认就会创建并使用venv，所以它开箱即用，不用手动配。

三、pip必会操作 + 国内镜像源加速

五个高频命令（背下来）

pip install requests              # 安装最新版
pip install requests==2.31.0      # 安装指定版本
pip list                          # 查看当前环境装了什么包
pip show requests                 # 查看某个包的版本、依赖、安装位置
pip uninstall requests            # 卸载

国内镜像源：把“龟速”调成“秒装”

pip默认从国外服务器下载，慢和超时不是你网速差，是路太远。国内镜像源 = 官方仓库的国内同步副本，内容一样，速度不是一个量级。

临时使用（只对本次安装生效）：

pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

一劳永逸（写入配置，以后默认走清华源）：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

执行完没有任何仪式感，但下次 pip install 直接起飞

清华源偶发抽风时可换阿里源：https://mirrors.aliyun.com/pypi/simple/

四、requirements.txt：环境的“存档”与“读档”

虚拟环境解决“打架”问题，requirements.txt解决“搬家”问题——它是一个纯文本清单，记着房间里所有包和精确版本。

存档（导出清单）

pip freeze > requirements.txt

打开看看，长这样：

requests==2.32.3
charset-normalizer==3.3.2
idna==3.7
urllib3==2.2.0
certifi==2024.8.30

读档（一键复现）

换电脑、发同学、部署服务器，通用三步：

python -m venv venv                 # ① 建新房间
# Windows: venv\Scripts\activate    # ② 激活
# Mac: source venv/bin/activate     # ② 激活
pip install -r requirements.txt     # ③ 按清单一键装齐

从此的标准工作流

新项目 = 建venv → pip装包 → freeze > requirements.txt

项目换机器只需要两样东西：代码 + requirements.txt。

venv文件夹本身从不搬家（为什么，见报错⑤）。

两个黄金习惯

• 项目根目录永远放一个 requirements.txt，别人拿到项目第一反应就是找它；
• 每次装了新包，随手重新 pip freeze > requirements.txt——存档要存最新的。

五、uv 最小上手：新一代工具，4条命令同款流程

第2篇预告过它：uv是社区这两年最火的新一代工具，Rust编写，安装、下载全并行，速度比pip快一个数量级，一个工具顶 venv + pip 两件套。

pip install uv                      # 安装 uv 本体
uv venv                             # 建环境（默认文件夹名 .venv）
uv pip install requests             # 秒级装包
uv pip freeze > requirements.txt    # 导出清单，与pip时代完全通用

激活、运行和venv一模一样（.venv\Scripts\activate），你已经学会的东西全部不作废。

现在就换吗？

我的建议：先把 venv/pip 这套“通用语言”用熟。

它是全网教程、报错帖、公司项目的公共基准，遇到问题到处有答案；uv是高效的“方言”，适合你已经吃透虚拟环境原理之后再切换。

后面偶尔会用uv演示，两条路线都会标注清楚。

六、常见报错：这6个，都在今天的射程内（重点！）

PowerShell激活报错“在此系统上禁止运行脚本”（Windows最高发）

现象：执行 .\venv\Scripts\Activate.ps1，红字 ...cannot be loaded because running scripts is disabled...

原因：PowerShell默认禁止运行脚本。

解法：打开PowerShell（不需要管理员），执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

输入 Y 确认，重开终端再激活即可。

这条命令只放开“本地脚本”的运行权限、只影响当前用户，放心执行。

激活了，(venv)却没出现 / pip还是全局的

原因：不在项目根目录执行的激活命令，或者终端窗口开错了。

解法：三步自查——

1. 看提示符最前面有没有 (venv)；
2. 敲 where pip（Mac：which pip）看路径指向哪；
3. 拿不准就直接用 python -m pip install 包名——跟着当前python走，永远不迷路。

下载龟速，最后ReadTimeoutError

原因：默认国外源，路远易超时。

解法：第三节镜像源。装到一半断掉不用慌，重跑一遍 pip install 即可，已下载的部分不浪费。

ERROR: Could not find a version that satisfies the requirement xxx

原因一：包名拼错了——比如装 opencv 找不到，其实包名叫 opencv-python。

原因二：这个包的新版本不支持你的Python版本。

解法：

1. 先去 https://pypi.org 搜包名核对；
2. 再考虑换/升Python版本——这就用上了第2篇的多版本共存。

能不能把venv文件夹拷给同学 / 拷到自己另一台电脑？

不能。 venv内部记录的路径是写死的，换台机器轻则失灵重则报错，而且它动辄几十上百MB。

正道：只拷“代码 + requirements.txt”，让新机器按第四节三步重建。

venv是一次性的，清单才是永恒的。

装了包，import还是ModuleNotFoundError—— 终极排查三连

遇到这个问题，按顺序查，别瞎折腾：

七、课后练习

1.给任意一个旧项目建venv，激活后 pip list 截图打卡——看看“空房间”里默认住着谁；

2.完整体验存档/读档：

做完这一条，换电脑恐惧症当场痊愈！

• 装 requests（记得用镜像源），pip freeze > requirements.txt
• 删掉整个venv文件夹
• 按“读档三步”重建
• 成功 import requests 

3.（选做） 用 uv 把练习2重跑一遍，汇报你的速度对比。

以上就是Python项目虚拟环境与依赖管理:venv / pip / requirements.txt实操教学的详细内容，更多关于Python虚拟环境与依赖管理的资料请关注脚本之家其它相关文章！

最新评论