Python虚拟环境venv与pip依赖管理使用教程及常见报错

脚本专家

很多Python项目跑不起来，不是代码本身的问题，而是依赖环境乱了。例如：pip install requests提示成功，运行时却报ModuleNotFoundError；升级了一个包的版本，另一个项目跟着挂掉；代码换到新电脑后缺少一堆包。这些问题的根源通常是：所有项目共用同一个全局Python环境，第三方包都堆在一起，互相干扰。

Python自带的venv可以为每个项目创建独立的虚拟环境，pip负责安装包，requirements.txt负责把当前环境里的依赖清单保存下来。下面把这条流程完整过一遍。

一、用venv为项目创建独立环境

先在终端进入项目根目录。不同系统下的创建和激活命令如下：

Windows cmd:

2. cd /d D:\myproject
3. python -m venv venv
4. venv\Scripts\activate

复制代码

Windows PowerShell:

2. cd D:\myproject
3. python -m venv venv
4. .\venv\Scripts\Activate.ps1

复制代码

macOS / Linux:

2. cd ~/myproject
3. python3 -m venv venv
4. source venv/bin/activate

复制代码

如果电脑里安装了多个Python版本，想在创建虚拟环境时指定版本，可以这样写：

2. py -3.13 -m venv venv

复制代码

看到命令行提示符最前面出现(venv)，说明虚拟环境已经激活。例如：

激活前：

2. C:\myproject>

复制代码

激活后：

2. (venv) C:\myproject>

复制代码

工作完成后，在终端执行deactivate即可退出虚拟环境。

二、验证pip是否真的进入了当前项目

激活前后分别执行一次以下命令：

2. pip --version

复制代码

未激活时，pip路径指向全局Python目录。激活后，pip路径应该变成当前项目下venv目录中的site-packages。路径发生变化，说明后续pip安装的包都会进入这个项目的虚拟环境，不会污染其他项目。

如果担心当前终端里的pip不是项目环境的pip，可以改用python -m pip install，这样pip一定会跟随当前python解释器，不会装错位置。

三、编辑器需要手动连接venv

在VSCode中新建venv后，编辑器不会自动使用它。需要手动选择解释器：

按Ctrl+Shift+P，输入Python: Select Interpreter，选择带有venv路径的python.exe。

选择成功后，VSCode右下角会显示venv标识。

PyCharm在新建项目时默认会创建并启用venv，通常不需要手动配置。

四、pip常用命令与国内镜像源

日常开发中，pip这几个命令足够用：

2. pip install requests
3. pip install requests==2.31.0
4. pip list
5. pip show requests
6. pip uninstall requests

复制代码

pip默认从PyPI官方源下载，速度慢且容易超时。可以使用清华镜像提升速度：

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

复制代码

如果希望以后自动使用镜像，不用每次手动加参数，可以写入pip配置：

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

复制代码

清华源偶尔不稳定，可以换成阿里源：

2. https://mirrors.aliyun.com/pypi/simple/

复制代码

五、用requirements.txt保存和恢复环境

虚拟环境解决的是项目之间依赖冲突，requirements.txt解决的是环境迁移问题。

导出当前环境的依赖清单：

2. pip freeze > requirements.txt

复制代码

生成的requirements.txt是纯文本，内容类似：

2. requests==2.32.3
3. charset-normalizer==3.3.2
4. idna==3.7
5. urllib3==2.2.0
6. certifi==2024.8.30

复制代码

新电脑或新环境恢复依赖时三步完成：

第一步，创建虚拟环境：

2. python -m venv venv

复制代码

第二步，激活虚拟环境。Windows cmd执行venv\Scripts\activate，macOS/Linux执行source venv/bin/activate。

第三步，根据清单安装依赖：

2. pip install -r requirements.txt

复制代码

以后的标准工作流就是：创建venv，用pip安装依赖，执行pip freeze > requirements.txt保存清单。项目迁移时只需要拷贝代码和requirements.txt，不需要拷贝venv文件夹本身。

六、代码中import报错的终极排查顺序

装包成功但import仍报ModuleNotFoundError时，按下面顺序排查：

1. 检查虚拟环境是否激活：命令行前缀有没有(venv)。

2. 确认包是否真的安装在了当前环境：执行python -m pip list，看包是否在列表中。

3. 检查编辑器解释器是否指向当前venv：在VSCode中查看右下角解释器状态，或重新执行Python: Select Interpreter。

这样基本能覆盖大多数import失败场景。

七、常见报错处理

1. PowerShell激活时报错“在此系统上禁止运行脚本”

这是因为PowerShell默认禁止执行脚本。以当前用户身份放开本地脚本执行权限即可，不需要管理员：

2. Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

复制代码

确认后，重开终端再激活venv。

2. 激活后没有(venv)，pip还是全局的

确认当前目录是不是项目根目录，激活的是不是对应终端。如果拿不准，直接用python -m pip install代替pip install，这样装包位置会跟当前python环境一致。

3. pip下载速度慢或出现ReadTimeoutError

原因是默认源在国外。解决方案是使用清华或阿里镜像源。如果下载中途断掉，重新执行一次pip install即可，已下载的缓存不会浪费。

4. 报错ERROR: Could not find a version that satisfies the requirement xxx

先检查包名是否拼写正确。例如要安装OpenCV，包名是opencv-python，不是opencv。也可以到pypi.org搜索确认包名，并确认该包当前版本是否支持你所用的Python版本。

5. 能不能把venv文件夹直接拷贝给别人或另一台电脑

不建议这样做。venv内部记录的路径是写死的，换机器后容易失效，而且venv文件体积大。正确做法是传递代码和requirements.txt，到新机器重建虚拟环境并执行pip install -r requirements.txt。

八、新一代工具uv简介

uv是社区中较新的Python包与环境管理工具，使用Rust编写，下载和安装速度比pip快很多。它的基础用法很容易上手：

2. pip install uv
3. uv venv
4. uv pip install requests
5. uv pip freeze > requirements.txt

复制代码

uv默认创建的虚拟环境目录是.venv，激活方式和普通venv一致。日常如果还没熟悉venv和pip，建议继续使用venv/pip，它们是目前教程、公司项目和社区资料中最通用的基础方案。

以上内容覆盖了Python项目依赖隔离、环境迁移和常见安装报错处理。在自己的旧项目上实际操作一遍，比死记命令更容易理解。