Python .venv 虚拟环境完整使用指南：告别包版本冲突

一、为什么需要 .venv 虚拟环境？

1.1 原生Python环境的痛点

很多Python初学者直接使用系统全局Python环境安装第三方库，长期使用会遇到两个致命问题：

包版本冲突：项目A需要requests==2.20，项目B需要requests==2.31，全局环境无法同时保留两个版本，升级一个项目就会导致另一个项目报错
环境污染：所有项目的依赖包全部安装在系统全局目录，冗余包越来越多，无法区分每个项目真正需要哪些依赖，项目迁移、部署时极其麻烦
权限风险：全局安装库需要管理员权限，容易篡改系统自带Python，导致系统自带脚本运行异常

1.2 什么是 .venv？

.venv 是Python官方内置的轻量虚拟环境工具，从Python3.3版本开始原生支持，无需额外pip安装第三方工具（无需virtualenv、conda）。

它的核心原理：为每一个Python项目创建独立、隔离的Python运行环境，每个项目拥有专属的Python解释器、pip工具和第三方依赖包，项目之间完全互不干扰。

二、.venv 完整实操步骤（全平台通用）

前提：确保电脑已配置Python环境变量，终端输入 python --version 可以正常输出版本号。

步骤1：进入项目根目录

打开终端/CMD/PowerShell，通过cd命令切换到你的Python项目文件夹，所有虚拟环境文件都会生成在当前项目目录下。

# 示例：切换到桌面的my_project项目
cd Desktop/my_project

步骤2：创建 .venv 虚拟环境

执行官方原生创建命令，无需安装任何依赖：

# 通用创建命令
python -m venv .venv

执行完成后，项目目录下会多出一个隐藏文件夹 .venv，内部包含：专属Python解释器、pip工具、site-packages依赖包存放目录。

小贴士：不要修改、不要进入.venv内部文件，所有操作统一通过终端命令执行即可。

步骤3：激活虚拟环境（分系统）

创建完成后必须激活环境，后续pip安装的包才会存放到当前项目的.venv中，而非全局环境。

✅ Windows系统

CMD终端：.venv\Scripts\activate.bat
PowerShell终端：.venv\Scripts\Activate.ps1

✅ Mac / Linux系统

source .venv/bin/activate

激活成功标志

终端命令行前面会多出(.venv) 标识，代表当前已经处于隔离的虚拟环境中：

(.venv) user@MacBook my_project %

步骤4：在虚拟环境中安装依赖包

激活环境后，正常使用pip安装库，所有包只会安装到当前项目的.venv目录，不会影响全局Python：

# 安装第三方库
pip install requests flask

# 查看当前环境已安装的依赖
pip list

# 导出项目依赖清单（核心功能，用于项目迁移）
pip freeze > requirements.txt

生成的 requirements.txt 文件会记录当前项目所有依赖包和对应版本，换电脑、部署服务器时可以一键还原环境。

步骤5：退出虚拟环境

开发完成后，想要切回系统全局Python环境，直接执行退出命令即可，全平台通用：

deactivate

执行后终端前方的 (.venv)标识消失，代表已退出虚拟环境。

步骤6：删除虚拟环境

虚拟环境不需要了，无需复杂命令，直接删除项目下的.venv文件夹即可，不会对系统全局环境造成任何影响。

三、项目迁移：一键还原虚拟环境

日常协作、项目部署时，队友不需要重新一个个安装包，只需要根据requirements.txt还原环境即可，标准工作流如下：

队友拿到项目代码（不含.venv文件夹，该文件夹禁止上传仓库）
进入项目目录，新建.venv并激活
一键安装所有依赖

# 一键还原所有依赖包
pip install -r requirements.txt

四、必看配置：Git忽略.venv文件夹

⚠️ 绝对不要把.venv文件夹上传到Git/GitHub代码仓库！

原因：.venv体积很大（几百MB），每个设备本地Python解释器不同，上传无意义，只需要保留requirements.txt即可。

在项目根目录新建 .gitignore 文件，写入以下内容自动忽略虚拟环境：

# 忽略虚拟环境
.venv/
venv/

# 忽略Python缓存文件
__pycache__/
*.pyc

五、常见报错解决方案

报错1：Windows PowerShell 禁止运行脚本

报错信息：Activate.ps1 因为在此系统上禁止运行脚本

解决方案：以管理员身份打开PowerShell，执行下方命令，选择A同意，之后即可正常激活环境：

Set-ExecutionPolicy RemoteSigned

报错2：python不是内部或外部命令

解决方案：安装Python时勾选Add Python to PATH，或者手动配置系统环境变量。

报错3：pip下载速度极慢

解决方案：激活虚拟环境后，切换国内清华镜像源：

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

六、IDE自动识别 .venv（VS Code/PyCharm）

1. VS Code

创建.venv之后，VS Code右下角会自动弹出选择解释器的提示，直接选中项目内的 .venv/bin/python（Mac/Linux）或 .venv/Scripts/python.exe（Windows）即可，后续终端打开会自动激活虚拟环境。

2. PyCharm

打开项目后，File -> Settings -> Project -> Python Interpreter，选择Existing environment，绑定项目下的.venv解释器即可。

七、开发最佳实践总结

一项目一环境：每个Python项目单独创建独立.venv，绝不共用全局环境
必存依赖清单：每次安装新包后，及时执行pip freeze更新requirements.txt
不上传虚拟环境：.venv永远加入.gitignore，只同步代码和依赖清单
优先使用原生venv：普通开发无需安装virtualenv和conda，原生.venv足够轻便好用