Python内置venv模块创建虚拟环境教程(Windows/Mac/Linux)

r

一、虚拟环境的隔离原理与工作机制

在默认情况下，使用 pip install 安装第三方包时，文件会被放置在操作系统的全局 site-packages 目录中。当多个项目共用该目录时，若项目 A 要求使用 Django 4.2，而项目 B 必须使用 Django 5.0，两者无法在同一全局环境中和平共存。

Python 官方通过 PEP 405 引入了内置虚拟环境标准。venv 模块的本质是在指定目录中建立一套轻量级的运行容器，其核心原理包括以下三点：

• 配置文件重定向（pyvenv.cfg）： 虚拟环境根目录下的 pyvenv.cfg 记录了宿主 Python 解释器的物理绝对路径（home 变量）以及是否允许继承全局包（默认 include-system-site-packages = false）。
• 轻量级可执行文件符号链接或副本： 虚拟环境内部并不完整复制几十兆的 Python 标准库，而是仅在其执行目录中建立指向全局解释器的轻量级符号链接（Unix 系统）或转发可执行文件（Windows 系统），标准库直接复用宿主环境。
• 独立的 site-packages 存储区： 虚拟环境拥有专属于自己的第三方库放置路径，所有的 pip 安装操作均被限制在该沙箱内，从而实现完全的物理隔离。

r

二、跨平台前置条件与模块可用性检查

由于 venv 属于 Python 3 的标准库模块，只要系统安装了 Python 3.3 或更高版本（推荐 Python 3.8+），即可直接调用。但在不同操作系统下，环境准备细节存在少许差异。

1. 检查 Python 版本

在开始操作前，请打开终端（Windows 推荐使用 PowerShell 或 CMD，macOS/Linux 打开内置 Terminal）执行版本查询指令：

# macOS / Linux / 现代 Windows 终端通用：
python3 --version

# Windows 官方安装包推荐的启动器：
py --version

如果输出类似 Python 3.10.12 或更高版本，则说明环境已就绪。

2. Linux 发行版的特殊注意事项

在 Windows 和 macOS 上，安装 Python 后 venv 与 ensurepip 会随标准库默认安装。但在 Ubuntu、Debian 以及部分基于它们衍生的 Linux 发行版中，操作系统维护团队为了精简基础解释器，将 venv 拆分成了独立的系统包。如果在 Ubuntu/Debian 上直接执行 python3 -m venv，可能会收到报错提示：The virtual environment was not created successfully because ensurepip is not available.

此时需通过发行版包管理器补齐依赖（以 Python 3.10 为例）：

# Ubuntu / Debian 系列
sudo apt update
sudo apt install python3-venv python3-pip

# Fedora / RHEL / CentOS 系列（通常自带，如缺失执行）：
sudo dnf install python3-virtualenv

三、创建虚拟环境的具体操作流程

创建虚拟环境的标准语法格式为：python -m venv <目标目录路径>。推荐将终端的工作目录切换至你的实际项目根目录下，然后将虚拟环境放置在名为 .venv 的文件夹中。以点号开头的目录在 Unix 系统下会自动隐藏，且 VS Code、PyCharm 等主流 IDE 均能自动识别 .venv 为项目默认解释器。

r

以下为在各系统项目根目录下的执行命令：

# 进入你的代码项目目录
cd C:\Users\Developer\Projects\my_project

# 使用 py 启动器创建 .venv 目录
py -3 -m venv .venv

# 或者直接使用 python 命令
python -m venv .venv

# 进入你的代码项目目录
cd ~/projects/my_project

# 执行 venv 模块创建虚拟环境
python3 -m venv .venv

四、跨平台目录树结构与核心组件对照

执行创建命令后，系统会在项目目录下生成一个独立的文件夹。Windows 与 Unix（macOS/Linux）在文件命名和目录排布上遵循了各自系统的习惯。理解两者的目录映射关系，是跨平台协作开发的基础。

r

五、激活与退出虚拟环境

单纯创建虚拟环境并不会自动改变当前的命令行状态。要让后续的所有命令（如 python main.py 或 pip install）都在该沙箱内生效，必须先激活（Activate）该虚拟环境。

激活脚本的本质作用是修改当前终端进程的环境变量 PATH，将虚拟环境的 bin 或 Scripts 目录置于系统所有搜索路径的最前面，从而实现对 python 和 pip 命令的临时劫持。

1. 各操作系统的激活指令

# 在项目根目录下执行
.venv\Scripts\activate.bat

# 在项目根目录下执行
.venv\Scripts\Activate.ps1

# 在项目根目录下执行
source .venv/bin/activate

2. 如何判断虚拟环境已成功激活

激活成功后，可以通过以下三种特征进行核验：

1. 命令行前缀标识： 终端命令行的最左侧会出现形如 (.venv) 的提示符，例如：
   (.venv) user@machine:~/my_project$ 或 (.venv) PS C:\my_project>
2. 检查 Python 解释器实际物理路径：
   macOS/Linux 下执行 which python，Windows 下执行 where python。输出的首行路径必须指向项目内的 .venv 文件夹，而非 /usr/bin/python3 或 C:\Python312\python.exe。
3. 检查 Python 内部前缀指针： 在终端执行如下一行代码：

   python -c "import sys; print(sys.prefix)"

   如果打印出来的路径是你的 my_project/.venv，则证明运行时已经完全切换至沙箱内部。

3. 退出虚拟环境（Deactivate）

当项目工作完成，或者需要切换到其他项目时，在当前已激活的终端中直接输入 deactivate 即可退出：

# 跨平台通用的退出命令
deactivate

执行后，命令行前缀的 (.venv) 标记会立即消失，终端的 PATH 环境变量会自动还原为初始状态。

六、依赖包管理与团队协作工程规范

虚拟环境搭建完成后，即可在激活状态下安全地使用 pip 进行安装，无需担心破坏系统级 Python 运行库，也绝对不要在虚拟环境中加 sudo。

1. 安装与升级包

# 激活状态下直接安装依赖
pip install requests fastapi uvicorn

# 检查当前虚拟环境中已安装的依赖列表
pip list

2. 导出与固化依赖清单（requirements.txt）

在多人协同或部署上线时，我们不需要也不应该把虚拟环境文件夹发送给他人。正确的做法是将当前环境精准安装的依赖包名称与版本号冻结为文本文件：

# 将当前沙箱依赖输出到 requirements.txt
pip freeze > requirements.txt

生成的文件内容示例：

fastapi==0.110.0
pydantic==2.6.4
requests==2.31.0
starlette==0.36.3
uvicorn==0.28.0

3. 在新设备上一键重构环境

当其他协作者克隆了代码，或在服务器部署时，只需执行以下标准三步即可重现完全一致的开发环境：

# 第一步：创建全新的空白虚拟环境
python3 -m venv .venv

# 第二步：激活该环境
source .venv/bin/activate  # Windows 用户执行 .venv\Scripts\activate.bat

# 第三步：依据清单批量安装所有依赖
pip install -r requirements.txt

4. 严格将虚拟环境排除在 Git 之外

这是团队开发中必须遵守的底线：切勿将虚拟环境目录提交至代码版本控制系统（如 Git）。

原因在于：虚拟环境中包含的大量二进制文件和符号链接具有强烈的平台与绝对路径依赖。在 Windows 上生成的 .venv 拷贝到 Linux 上完全无法运行；即便同为 macOS，换一台电脑也会因全局 Python 的安装路径不同而崩溃。

请务必在项目根目录的 .gitignore 文件中加入一行：

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

七、常见问题排查与关键避坑指南

1. 移动或重命名项目目录后 Python 报错找不到路径

现象： 将项目文件夹从 D:\old_dir 移动到 D:\new_dir 后，激活虚拟环境运行 pip 或 python 报错：Fatal error in launcher: Unable to create process using ... 或提示找不到文件。

原因： venv 在生成 Scripts/activate 脚本以及 pip.exe 打包时，内部硬编码写入了创建时的绝对路径，以确保解释器查找不会偏航。移动目录会破坏这层硬链接关系。

正确解法： 不要尝试手工修改那些被硬编码的文件。虚拟环境是可抛弃的轻量级消耗品。正确的做法是：退出环境，直接删除 .venv 文件夹，然后重新执行 python -m venv .venv 并基于 requirements.txt 重新安装依赖。整个过程只需几秒钟。

2. Linux 出现 ensurepip 不可用报错

如果创建时遇到 Error: Command '['.../.venv/bin/python3', '-Im', 'ensurepip', '--upgrade', '--default-pip']' returned non-zero exit status 1，请参考第二小节，使用 sudo apt install python3-venv 安装对应完整的系统包后再执行创建。

八、虚拟环境全生命周期工程总结

Python 内置的 venv 模块以零外部依赖、标准统一、结构清晰著称，是现代 Python 工程师日常开发中最基础也是最核心的工具。下图对 venv 从创建、开发、协同到销毁的完整生命周期管理原则进行了系统性归纳：

r

掌握 python -m venv .venv 与各平台的 activate 脚本，配合 pip freeze 和 .gitignore，即可在任何操作系统上保持整洁、可复现、无污染的 Python 开发工作流。