Python venv 虚拟环境与 pip 包管理完全指南：创建、激活与依赖隔离

Python venv 虚拟环境与 pip 包管理完全指南：创建、激活与依赖隔离

【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython

导读

venv是 Python 标准库中用于创建"虚拟环境"（virtual environment）的模块，它把某一特定版本的 Python 解释器与一批第三方包装进一个自包含的目录树中，使不同应用可以在各自环境里使用互不冲突的依赖版本。本指南基于 CPython 官方教程 Doc/tutorial/venv.rst，并结合 Lib/venv/init.py 的真实实现，完整讲解虚拟环境的背景动机、创建与激活方法、各平台激活脚本差异、以及用 pip 安装/升级/卸载/导出依赖的完整工作流。读完本文，你将能独立为任意 Python 项目搭建隔离环境，并熟练使用requirements.txt复现依赖。

一、为什么需要虚拟环境：依赖冲突的根源

Python 应用常常依赖标准库之外的第三方包，而不同应用对同一库的版本要求可能截然不同：

• 应用 A 依赖某个模块的1.0 版本（因为其代码按旧接口编写）；
• 应用 B 需要同一模块的2.0 版本（因为它要求 1.0 中存在的一个 bug 已被修复）。

若只有一个全局 Python 安装，无论装 1.0 还是 2.0，都必然让另一个应用无法运行——这就是依赖冲突问题。

虚拟环境的解决思路正如 Doc/glossary.rst 中对该术语的定义：一个协同隔离的运行时环境，允许用户和应用安装、升级 Python 发行包，而不会干扰同一系统上运行的其他 Python 应用。具体做法是：应用 A 使用装了 1.0 的环境，应用 B 使用装了 2.0 的另一环境；当应用 B 需要把某个库升级到 3.0 时，也完全不影响应用 A 的环境。

在 Lib/venv/init.py 的模块 docstring 中写明了其设计依据："Virtual environment (venv) package for Python. Based on PEP 405."——即该机制由 PEP 405 标准化。

二、创建虚拟环境：python -m venv

负责创建和管理虚拟环境的标准库模块就叫 venv。其关键行为是：venv 会安装运行命令所用解释器的那个 Python 版本（与--version选项报告的一致）。例如用python3.12执行命令，装进环境的就是 3.12。

在选定存放目录后，把 venv 模块当作脚本运行并传入目录路径即可：

$ python -m venv tutorial-env

该命令会在tutorial-env不存在时创建它，并在其内部生成包含 Python 解释器副本和各类支持文件的子目录。从源码看，ensure_directories() 会依次创建：

• bin/（Windows 上为Scripts/）：存放解释器可执行文件与激活脚本；
• lib/pythonX.Y/site-packages/（Windows 上为Lib/）：本环境的第三方包安装位置；
• include/：遵循 PEP 405 要求创建的本地头文件目录（Windows 上为Include）。

目录命名建议：.venv而非tutorial-env

官方教程建议常见的命名是.venv，理由有三：

1. 以.开头使其在 shell 中默认隐藏，保持项目根目录整洁；
2. 名称本身自解释（一眼看出它是 virtual environment）；
3. 不会与某些工具支持的.env环境变量定义文件混淆冲突。

创建时究竟发生了什么

结合 EnvBuilder.create()，一次创建操作的核心步骤包括：

1. ensure_directories()：计算并建立bin、lib、include目录结构（上文所述）；
2. create_configuration()：写出 pyvenv.cfg 配置文件；
3. setup_python()：把宿主解释器以符号链接（POSIX 默认）或复制（Windows 默认）的方式放入环境。POSIX 分支还会顺带生成python、python3、python3.X三个入口（Lib/venv/init.py）；
4. _setup_pip()（默认开启）：调用新环境的 Python 执行ensurepip --upgrade --default-pip引导安装 pip（Lib/venv/init.py）；
5. setup_scripts()：把激活/停用脚本装入bin或Scripts（Lib/venv/init.py）。

生成的pyvenv.cfg会记录环境与宿主的关系，例如：

home = /usr/local/bin include-system-site-packages = false version = 3.13.0 executable = /usr/local/bin/python3.13 command = /usr/local/bin/python3.13 -m venv /path/to/tutorial-env

• home：宿主 Python 所在目录（该环境解释器的符号链接目标）；
• include-system-site-packages：是否向环境暴露全局 site-packages（默认false）；
• version：创建环境的 Python 版本号；
• command：重建该环境的完整命令行（用于诊断复现）。

venv 命令行选项速查

python -m venv的实际入口在 Lib/venv/main.py，参数解析位于 Lib/venv/init.py，主要选项如下：

例如，为当前项目创建标准隔离环境：

$ python -m venv .venv

注意：--upgrade与--clear不能同时使用（Lib/venv/init.py 会抛出ValueError）。

三、激活与停用虚拟环境

创建完成后需要激活，使 shell 会话中的python指向环境内的解释器。

各平台激活命令

Windows（在tutorial-env目录所在会话中）：

tutorial-env\Scripts\activate

Unix 或 macOS（bash shell）：

source tutorial-env/bin/activate

激活脚本按 shell 分发，对应源码位于 Lib/venv/scripts：bash 用common/activate、csh 用posix/activate.csh、fish 用common/activate.fish、PowerShell 用common/Activate.ps1、Windows cmd 用nt/activate.bat。原文档特别提示：若你使用csh 或 fish，请改用相应的activate.csh与activate.fish。

激活后发生了什么

激活会做两件事（以 Lib/venv/scripts/common/activate 的实现为准）：

1. 修改 shell 提示符：在PS1前加(环境名)，例如：

$ source ~/envs/tutorial-env/bin/activate (tutorial-env) $

2. 修改环境变量：导出VIRTUAL_ENV、VIRTUAL_ENV_PROMPT，并把$VIRTUAL_ENV/bin插入PATH最前，使python、pip均来自当前环境。此时sys.path指向环境自身的site-packages：

(tutorial-env) $ python Python 3.5.1 (default, May 6 2016, 10:59:36) ... >>> import sys >>> sys.path ['', '/usr/local/lib/python35.zip', ..., '~/envs/tutorial-env/lib/python3.5/site-packages'] >>>

同时脚本会清空PYTHONHOME（Lib/venv/scripts/common/activate），并调用hash -r刷新命令缓存。

关键警告：激活不会改动PYTHONPATH

原文档特别强调：激活虚拟环境不会以任何方式修改PYTHONPATH变量。如果PYTHONPATH中含有与当前环境 Python 版本不兼容的代码路径，可能引发意外结果。最佳实践是在 bash 中执行：

unset PYTHONPATH

（其他 shell 使用对应的等效写法。）

停用虚拟环境

在终端中键入：

(tutorial-env) $ deactivate

deactivate会还原被保存的PATH、PS1，并删除VIRTUAL_ENV、VIRTUAL_ENV_PROMPT（Lib/venv/scripts/common/activate）。

四、用 pip 管理第三方包

进入环境后，即可用 pip 安装、升级、卸载包。默认情况下 pip 从Python Package Index（PyPI）获取包。pip 拥有install、uninstall、freeze等众多子命令。

下文示例中的novas、requests仅为演示包名，教程采用python -m pip形式调用以保证使用的是当前环境内的 pip。

安装最新版本

指定包名即可安装最新版：

(tutorial-env) $ python -m pip install novas Collecting novas Downloading novas-3.1.1.3.tar.gz (136kB) Installing collected packages: novas Running setup.py install for novas Successfully installed novas-3.1.1.3

安装指定版本

用包名==版本号精确指定版本：

(tutorial-env) $ python -m pip install requests==2.6.0 Collecting requests==2.6.0 Using cached requests-2.6.0-py2.py3-none-any.whl Installing collected packages: requests Successfully installed requests-2.6.0

若重复执行该命令，pip 会发现目标版本已安装而不做任何操作；换用其他版本号则安装对应版本。

升级到最新版

使用--upgrade将包升级到最新版：

(tutorial-env) $ python -m pip install --upgrade requests Collecting requests Installing collected packages: requests Found existing installation: requests 2.6.0 Uninstalling requests-2.6.0: Successfully uninstalled requests-2.6.0 Successfully installed requests-2.7.0

卸载与查看

卸载：uninstall后跟一个或多个包名，即可从环境中移除：

(tutorial-env) $ python -m pip uninstall requests

查看单个包信息：用show展示包的元数据：

(tutorial-env) $ python -m pip show requests --- Metadata-Version: 2.0 Name: requests Version: 2.7.0 Summary: Python HTTP for Humans. Home-page: http://python-requests.org Author: Kenneth Reitz Author-email: me@kennethreitz.com License: Apache 2.0 Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-packages Requires:

其中Location直接指向该虚拟环境自身的site-packages目录，直观体现了依赖隔离效果。

列出全部已装包：用list：

(tutorial-env) $ python -m pip list novas (3.1.1.3) numpy (1.9.2) pip (7.0.3) requests (2.7.0) setuptools (16.0)

五、用 requirements.txt 冻结与复现依赖

pip freeze会输出与install输入格式一致的已装包清单，因此是记录与复现依赖的利器。常见做法是把输出写入requirements.txt：

(tutorial-env) $ python -m pip freeze > requirements.txt (tutorial-env) $ cat requirements.txt novas==3.1.1.3 numpy==1.9.2 requests==2.7.0

之后将requirements.txt提交到版本控制并随应用一起发布。其他开发者/服务器只需一条命令即可安装全部所需依赖：

(tutorial-env) $ python -m pip install -r requirements.txt Collecting novas==3.1.1.3 (from -r requirements.txt (line 1)) ... Collecting numpy==1.9.2 (from -r requirements.txt (line 2)) ... Collecting requests==2.7.0 (from -r requirements.txt (line 3)) ... Installing collected packages: novas, numpy, requests Running setup.py install for novas Successfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0

这套「freeze → 入库 →-r还原」的工作流，正是现代 Python 项目依赖锁定的基础形态。

六、源码级速览：venv 的实现骨架

理解venv的源码能让排查问题更有把握。整个实现集中在标准库 Lib/venv/init.py（约 700 行），其骨架是 EnvBuilder 类——官方文档称该类允许"定制虚拟环境创建过程"，构造参数包括：

• system_site_packages：为True时向环境开放全局 site-packages；
• clear：目标目录已存在时先清空再创建；
• symlinks：True用符号链接、False用复制、None采用平台默认（Lib/venv/init.py 中os.name != 'nt'，即非 Windows 默认链接）；
• upgrade/with_pip/prompt/upgrade_deps/scm_ignore_files等。

从结构可以推断，EnvBuilder 预留了供子类覆写的扩展点：create()在创建流程末尾调用post_setup()（默认空实现，Lib/venv/init.py），子类可在此追加安装额外包或脚本——这正是很多脚手架工具定制 venv 的入口。模块级还提供了便捷函数 create() 供程序化调用。

值得注意的细节：即使不激活环境，也可以直接调用环境内的解释器来运行其中的包（例如在 CI 中省去激活步骤）；激活的意义仅在于让python/pip等命令名默认指向环境。

七、延伸阅读

• venv 模块官方参考文档：全部 CLI 选项与EnvBuilderAPI 的权威说明；
• 安装 Python 模块（pip 完整文档）：本教程中 pip 相关章节的完整参考；
• 安装 Python 包教程：编写并分发你自己的包到 PyPI 的入门指引；
• 词汇表：virtual environment：官方术语定义；
• PEP 405：venv 机制的设计规格与背景。

结语

从本教程可见，venv + pip 的组合提供了完整的最小依赖隔离方案：python -m venv创建自包含目录树，激活脚本按 shell 精准地改写PATH与提示符，而freeze/requirements.txt/install -r则让依赖状态可记录、可复现。理解 Lib/venv/init.py 中pyvenv.cfg、site-packages、setup_python的实现逻辑，能帮助你在遇到环境异常时快速定位是「链接失败」「pip 未引导」还是「PYTHONPATH残留」等原因，从而把虚拟环境真正变成可控的工程资产。

【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython