Python 标准库：venv（虚拟环境创建与管理）

venv 是 Python 标准库中用于创建虚拟环境的模块。它为项目提供独立的解释器入口和第三方包安装位置，便于分别管理不同项目的依赖，减少包版本冲突。

虚拟环境建立在已有 Python 安装之上，不会自动下载其他 Python 解释器，也不是独立的操作系统。使用时，应将项目代码与环境目录分开保存，并通过依赖清单记录环境的重建方式。

一、使用方式与适用范围

1、调用模块

venv 通常通过命令行使用：

python -m venv .venv

其中：

• python：执行创建操作的 Python 解释器。

• -m venv：以模块方式运行 venv。

• .venv：虚拟环境的保存目录。

venv 随 Python 提供，通常无需通过 pip 安装。部分 Linux 发行版将相关组件单独打包，缺少时需要通过系统包管理器补装。

2、主要应用

（1）项目依赖隔离

分别安装各项目需要的第三方包，避免所有项目共用一个包安装目录。

（2）依赖版本管理

为不同项目保留不同的包版本，减少升级某个包对其他项目的影响。

（3）开发与测试

在独立环境中试用新依赖、检查兼容性或验证安装过程。

（4）环境重建

根据项目代码与依赖清单，在其他位置重新建立运行环境。

3、与 pip 的分工

venv 负责创建环境，pip 负责在指定环境中安装和管理包。

基本流程为：

选择基础解释器 → 创建环境 → 使用环境解释器 → 安装依赖 → 运行项目

环境创建与包安装是两个步骤。创建虚拟环境后，OpenPyXL、python-docx 等第三方包仍需按项目需要安装。

二、核心概念与环境结构

1、基础解释器

基础解释器（Base Interpreter）是用于创建虚拟环境的已有 Python 解释器。

python -m venv .venv

该命令使用 python 当前指向的解释器创建环境。

如果需要使用另一套 Python，应明确调用那套解释器，而不是通过更改环境目录名选择版本。

在 Windows PowerShell 中，可使用解释器的完整路径：

& "C:\Python\python.exe" -m venv .venv

路径应替换为实际安装位置。PowerShell 中，执行带引号的程序路径需要使用调用运算符 &。

2、虚拟环境

虚拟环境（Virtual Environment）包含解释器入口、环境配置和独立的包安装目录。

默认情况下，基础环境中的第三方包不会自动对虚拟环境可见。不同虚拟环境也各自管理安装的包。

这种隔离主要针对 Python 解释器配置与包查找路径，不会隔离项目文件、网络或系统权限。

3、环境目录

.venv 是常用目录名，也可以使用其他名称：

python -m venv report_env

Windows 环境中的主要内容包括：

• pyvenv.cfg：记录基础 Python 等环境配置。

• Scripts：保存解释器入口、激活脚本和已安装命令。

• Lib/site-packages：保存第三方包。

macOS 和 Linux 通常使用 bin 保存解释器入口和脚本，第三方包位于 lib 下对应 Python 目录中的 site-packages。

这些内容由工具维护，不宜手动调整内部文件。

4、项目与环境的关系

建议将环境放在项目目录中，并与源代码并列：

• report_project/main.py：项目代码。

• report_project/requirements.txt：依赖清单。

• report_project/data：输入数据。

• report_project/output：输出结果。

• report_project/.venv：虚拟环境。

项目代码、数据和输出文件不应保存在 .venv 内部，以便环境删除后能够重新创建。

三、创建与确认环境

1、创建项目目录

以下命令可在 Windows 命令提示符或 PowerShell 中执行：

python -m venv .venv

macOS 和 Linux 中，创建时通常使用：

python3 -m venv .venv

命令完成后，项目目录中生成 .venv。

默认创建过程会安装 pip，但不会自动安装项目所需的第三方包。

2、确认基础解释器

创建前，可以检查当前解释器：

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

第一条命令显示 Python 版本，第二条命令显示解释器位置。

安装了多套 Python 时，应先确认所选解释器，再创建环境。环境名称本身不能说明其实际使用的解释器。

3、直接检查环境解释器

Windows：

.\.venv\Scripts\python.exe -c "import sys; print(sys.executable)"

macOS 和 Linux：

./.venv/bin/python -c "import sys; print(sys.executable)"

这些命令直接调用环境中的解释器，不要求事先激活。

4、检查 pip

Windows：

.\.venv\Scripts\python.exe -m pip --version

macOS 和 Linux：

./.venv/bin/python -m pip --version

输出会包含 pip 的版本及安装位置。安装位置应位于当前虚拟环境中。

四、激活、运行与退出

1、Windows PowerShell 激活

在项目目录中执行：

.\.venv\Scripts\Activate.ps1

激活后，终端提示符通常会出现 (.venv)。

如果 PowerShell 的脚本执行策略阻止激活，可以直接调用环境解释器，无需为运行项目而修改策略：

.\.venv\Scripts\python.exe main.py

2、Windows 命令提示符激活

在命令提示符中执行：

.venv\Scripts\activate.bat

PowerShell 与命令提示符使用不同的激活脚本，应根据实际终端选择。

3、macOS 与 Linux 激活

在 bash 或 zsh 中执行：

source .venv/bin/activate

其他 Shell 应使用对应的激活脚本。

4、激活的作用

激活脚本主要调整当前终端的环境变量，使环境中的解释器和命令优先被找到。

激活后，可以使用简短命令：

python -m pip list

激活不会将项目文件移入环境，也不会自动改变工作目录。

激活状态主要影响当前终端会话及其后启动的子进程。新开的终端通常需要重新激活，已经运行的程序也不会因此切换解释器。

5、确认实际运行环境

python -c "import sys; print(sys.executable); print(sys.prefix != sys.base_prefix)"

输出包括：

• 当前解释器的位置。

• 是否正在使用 venv 虚拟环境的判断结果。

对于 venv，sys.prefix != sys.base_prefix 为 True，表示当前解释器处于虚拟环境中。

提示符和 VIRTUAL_ENV 环境变量不能完全代替这一检查，因为直接调用虚拟环境解释器时也可以正常使用环境，而无需激活。

6、退出环境

在已经激活的终端中执行：

deactivate

该命令恢复当前终端激活前的相关设置，不会卸载包或删除环境。

关闭终端也会结束该终端中的激活状态。

五、依赖安装与检查

以下命令假定已激活目标环境；也可以将 python 替换为环境解释器的完整路径。

1、安装项目依赖

python -m pip install openpyxl python-docx

使用 python -m pip，可以明确由当前 Python 解释器运行 pip，减少解释器与 pip 不一致的问题。

安装完成后，可检查导入：

python -c "import openpyxl; import docx; print('依赖导入成功')"

包的安装名称与导入名称可能不同，例如安装 python-docx，代码中使用 import docx。

2、查看已安装的包

python -m pip list

查看某个包的详细信息：

python -m pip show openpyxl

输出中的安装位置可用于确认包是否安装在预期环境中。

3、升级与卸载

升级指定包：

python -m pip install --upgrade openpyxl

卸载指定包：

python -m pip uninstall openpyxl

升级会改变当前环境中的依赖状态。对于已经能够正常运行的项目，应在验证兼容性后更新依赖清单。

卸载某个包不一定会自动清理其安装时引入的全部依赖。

4、检查依赖关系

python -m pip check

该命令检查已安装包声明的依赖是否缺失或存在版本不兼容。

检查通过不代表程序逻辑和所有功能都已验证，仍需运行项目中的实际处理流程。

5、可选的 pip 更新

python -m pip install --upgrade pip

该命令更新当前环境中的 pip，需要能够访问所配置的软件包索引。

更新 pip 与升级 Python 解释器是不同的操作。

六、依赖记录与环境重建

1、导出依赖清单

在 Windows 命令提示符或 bash、zsh 中执行：

python -m pip freeze > requirements.txt

在 Windows PowerShell 中，可显式使用 UTF-8 输出：

python -m pip freeze | Out-File -Encoding utf8 requirements.txt

pip freeze 通常将已安装包及其版本输出为可供 pip 读取的依赖条目。

该命令记录当前环境状态，并不会自动判断哪些包是项目直接需要的。因此，宜在依赖明确的项目环境中导出。

2、依赖清单的范围

依赖清单用于记录包安装要求，但不是完整的运行环境副本。

它通常不能单独记录：

• Python 解释器本身。

• 操作系统及系统组件。

• 外部程序和驱动。

• 项目数据、配置与环境变量。

• 所有平台相关的安装条件。

pip freeze 生成的是已安装依赖的记录，不是能够保证跨平台完全一致的锁定结果。默认输出还会省略部分包管理工具。

3、在新位置重建环境

将项目代码和 requirements.txt 放到新位置后，重新创建环境。

Windows PowerShell：

.\.venv\Scripts\python.exe main.py

macOS 和 Linux：

./.venv/bin/python main.py

重建时，应选择符合项目要求的 Python 解释器。

如果依赖清单包含本地路径、可编辑安装或私有包源，还需要确保相关资源在目标环境中可用。

4、更新依赖记录

安装、升级或移除依赖后，应先确认项目运行正常，再更新清单。

对于需要长期维护的项目，可以分别记录：

• 项目直接依赖及允许的版本范围。

• 已验证环境中的具体安装版本。

前者便于表达项目要求，后者便于重建某次验证过的环境。

七、项目应用示例

1、准备环境

在项目目录中执行：

python -m venv .venv

Windows PowerShell 中直接安装依赖：

.\.venv\Scripts\python.exe -m pip install openpyxl python-docx

此流程不依赖激活状态。

2、编写处理程序

将以下代码保存为 main.py：

3、运行项目

Windows：

.\.venv\Scripts\python.exe main.py

macOS 和 Linux：

./.venv/bin/python main.py

程序在当前工作目录的 output 中生成：

• students.xlsx。

• report.docx。

虚拟环境提供第三方包，输出位置仍由程序中的路径设置决定。

4、记录项目依赖

验证结果后，使用同一环境导出依赖。

Windows PowerShell：

    Out-File -Encoding utf8 requirements.txt

这样可以避免将其他 Python 环境中的包误写入项目清单。

八、创建选项与程序接口

1、自定义提示名称

python -m venv .venv --prompt report

激活后，提示符通常显示为 (report)。

该选项只调整提示名称，不改变环境目录和解释器版本。

2、创建时更新基础依赖

python -m venv .venv --upgrade-deps

该选项在创建过程中更新基础包管理依赖，当前主要是 pip，需要访问软件包索引。

它不会安装或更新项目的全部第三方包。

3、允许访问基础环境的包

python -m venv .venv --system-site-packages

该选项允许环境访问基础 Python 的系统级包目录。

这会减弱环境的包隔离程度。需要清晰管理项目依赖时，通常保留默认隔离方式。

4、不安装 pip

python -m venv .venv --without-pip

该选项跳过 pip 初始化，适用于由其他工具统一管理包安装的情形。

一般入门项目无需使用。

5、清空目标后重建

python -m venv .venv --clear

--clear 会先删除目标环境目录中的内容，再创建环境。

它不同于普通的重复创建命令，应确保目标目录只保存可重建的环境文件。

6、解释器升级选项

python -m venv .venv --upgrade

该选项用于基础 Python 已在原位置升级后的环境调整，不会自动下载另一套 Python，也不是通用的跨版本迁移命令。

切换解释器版本时，重新创建环境并安装依赖通常更便于验证。

7、通过 Python 创建环境

EnvBuilder 用于通过程序创建或定制环境。

与命令行默认行为不同，使用该接口时需要显式设置 with_pip=True，才能要求初始化 pip。

创建完成不会自动激活调用程序所在终端，也不会切换当前正在运行的 Python 进程。

九、常用命令与接口速览

1、创建环境

python -m venv .venv

创建虚拟环境。

python -m venv .venv --prompt name

指定激活后的提示名称。

python -m venv .venv --upgrade-deps

创建环境并更新基础包管理依赖。

python -m venv --help

查看当前解释器支持的创建选项。

2、激活与退出

.\.venv\Scripts\Activate.ps1

在 Windows PowerShell 中激活。

.venv\Scripts\activate.bat

在 Windows 命令提示符中激活。

source .venv/bin/activate

在 macOS、Linux 的 bash 或 zsh 中激活。

deactivate

退出当前终端的激活状态。

3、环境检查

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

查看当前解释器位置。

python -m pip --version

查看当前 pip 及其安装位置。

python -m pip list

列出已安装包。

python -m pip check

检查已安装包声明的依赖关系。

4、依赖安装与记录

python -m pip install package_name

安装指定包。

python -m pip install -r requirements.txt

根据依赖清单安装。

python -m pip freeze

输出当前环境中的依赖记录。

python -m pip uninstall package_name

卸载指定包。

5、程序接口

venv.EnvBuilder(with_pip=True)

创建环境构建器。

builder.create(env_dir)

在指定目录创建环境。

十、使用注意事项

1、终端与开发工具的解释器

终端激活环境，不代表编辑器、调试器或 Notebook 已经使用同一解释器。

在开发工具中，应选择项目虚拟环境对应的解释器。Notebook 还需要确认当前内核。

发生“终端可以导入，但编辑器运行失败”等问题时，应分别检查实际执行位置的 sys.executable。

2、包安装位置

出现 ModuleNotFoundError 时，应先确认运行程序的解释器，再检查包是否安装在该环境中。

不要只根据安装命令曾经成功，就认定所有 Python 环境都能够导入该包。

使用环境解释器执行 -m pip，可以明确安装目标。

3、环境迁移

虚拟环境内部可能包含指向原位置和基础解释器的路径信息，不宜将整个环境目录直接复制到另一台设备或随意移动。

迁移项目时，应保留代码、数据及依赖清单，在目标位置重新创建环境。基础 Python 被卸载或路径发生变化后，也应检查并重建相关环境。

4、环境删除

删除前，应停止使用该环境的程序、调试会话或 Notebook 内核，并退出激活状态。

随后删除 .venv 目录即可，无需逐个卸载其中的包。

前提是项目代码和数据保存在环境目录之外。环境删除不会自动清理项目目录中的输出文件。

5、版本控制

项目代码和依赖清单应纳入版本控制，虚拟环境目录通常不应提交。

可在项目的 .gitignore 中加入：

.venv/

环境可以重新创建，代码、配置和必要的数据说明则需要单独保存。

6、隔离范围

venv 不提供虚拟机或容器级别的系统隔离，也不会限制程序访问当前用户能够访问的文件。

它解决的是 Python 项目依赖与解释器使用的组织问题。系统库、外部程序和硬件驱动仍需根据项目要求配置。

小结

venv 为项目建立独立的 Python 包环境。明确基础解释器、激活状态与实际运行解释器的关系，使用对应的 pip 管理依赖，并保留可重建的依赖记录，可减少环境冲突并提高项目维护效率。

“点赞有美意，赞赏是鼓励”