为什么virtualenv现在默认不再捆绑wheel包?

Nora
Nora
发布时间:2026-11-20| 9人浏览过
原创

深入解析新版 virtualenv 在 Python 3.12+ 下不再默认捆绑 wheel 包的原因,详解 PEP 517 构建隔离机制、wheel 格式与工具库分离原理及常见遗留场景应对策略。

Python 虚拟环境机制 打包规范:PEP 517 / PEP 518 生效版本:virtualenv 20.23.0+ / Python 3.12+
为什么virtualenv现在默认不再捆绑wheel包?
在新版本 virtualenv(针对 Python 3.12 及以上环境)中,创建虚拟环境后执行包列表检查,会发现曾经与 pip、setuptools 并称“三件套”的 wheel 包已经不再默认预装。这一调整并非功能倒退,而是现代 Python 打包标准成熟后的主动精简:现代 pip 原生即可解包安装预编译的 .whl 文件,并不依赖环境中的 wheel 库;而在需要从源码包即时编译 wheel 时,PEP 517 构建隔离机制会在独立的临时沙箱中动态拉取构建工具。移除默认捆绑不仅避免了运行环境的冗余污染,加快了虚拟环境初始化速度,也使 virtualenv 与 Python 官方标准库 venv 的精简规范保持了完全一致。

概念澄清:wheel 格式与 wheel 命令行工具的区别

很多开发者在初次遇到该变化时会产生疑问:“如果环境中没有 wheel 包,那我还能正常安装 wheel 格式的依赖包吗?”要解答这个疑惑,首先需要厘清两个长期被同名指代的关键概念:

  • 作为文件格式的 wheel(.whl):它是 Python 官方推荐的二进制或纯 Python 分发格式(PEP 427)。其物理本质是一个带有固定目录约定的标准 ZIP 归档,内含打包好的模块源码、编译后的动态链接库以及携带依赖清单与安装记录的 .dist-info 元数据目录。
  • 作为 Python 依赖库的 wheel:它是托管在 PyPI 上的一个 Python 软件包(即通过 pip install wheel 获得的工具)。其主要功能是提供 wheel 命令行工具,以及向传统 setup.py 注入 bdist_wheel 命令,用于把工程源码构建打包为 .whl 文件。

日常使用 pip 安装绝大部分常见三方库时,下载下来的已经是开发者在 PyPI 上发布好的现成 .whl 文件。pip 在处理此类文件时,依靠其内置的 ZIP 解压与元数据解析逻辑即可直接完成文件放置,整个过程自始至终都不需要调用任何宿主环境里的 wheel 库代码。

为什么virtualenv现在默认不再捆绑wheel包?
图 1:wheel 分发格式(消费端)与 wheel 工具库(生产端)的职责边界划分

历史回溯:过去为什么 virtualenv 必须捆绑 wheel?

既然消费现成 wheel 不需要 wheel 库,那为什么过去的 virtualenv 在长达数年的时间里都坚持将 wheel 作为默认种子包(seed package)强制注入到每个新环境呢?这源于早期 Python 打包生态的历史局限。

在 PEP 517 规范普及之前,若某个项目在 PyPI 上仅提供了源码分发包(sdist,如 .tar.gz 格式),pip 在安装时需要先将其编译打包为 wheel,再行安装。而在旧的打包体系下,pip 是直接在当前目标虚拟环境中就地执行构建命令的:

  1. pip 尝试在当前环境调用 python setup.py bdist_wheel 生成 wheel;
  2. 如果当前环境中没有安装 wheel 库,该命令就会执行失败;
  3. 一旦生成 wheel 失败,旧版 pip 只能回退并直接执行臭名昭著的 python setup.py install。

setup.py install 是一种极不规范的传统安装方式:它不会生成记录已装文件哈希与路径的 RECORD 清单,导致后续使用 pip uninstall 时经常无法彻底清理文件;同时安装过程会直接在当前环境中运行未经沙箱隔离的任意 Python 脚本,极易造成构建期副作用污染。为了规避该问题,旧版 virtualenv 别无选择,只能将 pip、setuptools 与 wheel 捆绑为“铁三角”,保证任何虚拟环境都能默认具备构建 wheel 的基本能力。

架构演进:PEP 517 构建隔离让环境彻底解耦

随着 Python 打包规范的演进,PEP 517(构建前端与后端分离标准)与 PEP 518(基于 pyproject.toml 的声明式依赖)确立了现代打包机制。在这一架构下,源码包的构建流程发生了根本性变革:

从 pip 23.1 开始,pip 彻底移除了向 setup.py install 回退的后备逻辑,转而全面启用构建隔离(Build Isolation)机制。当 pip 检测到需要从源码编译安装包时,其执行流程如下:

  • 创建独立临时沙箱:pip 在操作系统的临时文件目录(如 /tmp/pip-build-env-xxxx)中即时生成一个微型的临时虚拟环境;
  • 按需注入构建依赖:pip 读取源码包根目录下的 pyproject.toml,解析 [build-system] requires 中声明的构建依赖(例如声明了 ["setuptools", "wheel"] 或者是现代化后端 hatchling、flit_core),并在临时沙箱内按需安装这些依赖;
  • 沙箱内编译产出:在隔离沙箱中执行构建,顺利编译出标准的 .whl 分发文件并交付给 pip;
  • 目标环境部署与沙箱销毁:pip 将产出的 .whl 解包安装至用户的目标虚拟环境,随后彻底销毁临时沙箱。
为什么virtualenv现在默认不再捆绑wheel包?
图 2:PEP 517 动态构建隔离机制与临时沙箱编译流程图解

在构建隔离机制下,即使源码包的编译确实需要 wheel 或 setuptools,它们也只会在临时的沙箱环境中短暂存在,用完即弃。用户的目标虚拟环境全程处于“受体”角色,只接收最终编译好的 wheel 产物。因此,在目标虚拟环境中常驻预装 wheel 库已经彻底失去了技术存在的必要性。

默认行为实测:创建新环境与包安装验证

我们可以通过一系列具体的操作命令,在终端中直观验证当前 virtualenv 的默认行为以及依赖安装情况。

步骤 1:创建全新的虚拟环境

在终端中指定使用 Python 3.12+ 解释器创建一个名为 demo_env 的虚拟环境:

命令Shell
virtualenv demo_env
示例执行输出Console
created virtual environment CPython3.12.2.final.0-64 in 128ms
  creator CPython3Posix(dest=/path/to/demo_env, clear=False, no_vcs_ignore=False, global=False)
  seeder FromAppData(download=False, pip=bundle, via=copy, app_data_dir=/path/to/app-data)
    added seed packages: pip==24.0
  activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator

从输出中的 added seed packages: pip==24.0 可以明确看到,种子包安装器(seeder)仅注入了 pip,不再包含以往常见的 setuptools 和 wheel。

步骤 2:激活环境并检查预装包

命令Shell
source demo_env/bin/activate
pip list
示例执行输出Console
Package Version
------- -------
pip     24.0

环境处于绝对纯净的单一包状态,排除了预装库对后续项目依赖解析的潜在干扰。

步骤 3:常规包安装验证

在未预装 wheel 的环境下,直接安装主流第三方库(如 httpx):

命令Shell
pip install httpx
示例执行输出Console
Collecting httpx
  Downloading httpx-0.27.0-py3-none-any.whl (75 kB)
Collecting certifi (from httpx)
  Downloading certifi-2024.2.2-py3-none-any.whl (163 kB)
...
Successfully installed certifi-2024.2.2 httpcore-1.0.4 httpx-0.27.0 idna-3.6 sniffio-1.3.1

安装过程完全通畅无误,pip 迅速完成了 wheel 包的下载与解包释放,证明日常开发依赖的安装完全不受 wheel 库缺失的影响。

为什么virtualenv现在默认不再捆绑wheel包?
图 3:创建虚拟环境、核对种子清单及验证安装的实操完整路径

特殊场景应对:何时需要重新引入 wheel?

尽管日常安装无需 wheel,但在以下少数特殊开发或运维场景中,环境中依然需要提供 wheel 库:

  • 本地项目打包与轮子分发:如果你是库的维护者,需要在本地主动执行 pip wheel . 或使用传统构建脚本打包 .whl 文件分发到私有仓库,需要环境内具备 wheel 工具支持。
  • 离线/内网 CI 且禁用了构建隔离:在部分安全性极高或完全离线的内网流水线中,由于无法动态拉取临时构建依赖,工程师通常会附加 --no-build-isolation 参数运行 pip。此时 pip 不再创建临时沙箱,必须直接借助宿主环境中的工具进行编译。若源码包属于传统项目且环境中无 wheel,构建就会中断。
  • 直接调用内部 API 的历史脚本:极少数陈旧运维脚本中存在显式的 import wheel 语句。
解决方案:当遇到上述场景时,可以通过以下方式按需补齐或恢复旧版捆绑行为:

方式一:在当前环境中直接安装(最常用)

命令Shell
pip install wheel setuptools

方式二:创建虚拟环境时显式启用捆绑参数

如果希望 virtualenv 在创建阶段就自动还原旧版预装行为,可在创建时传递参数:

命令Shell
virtualenv --wheel=bundle --setuptools=bundle my_legacy_env

方式三:通过环境变量全局生效

在 CI/CD 机器或个人配置文件(如 ~/.bashrc)中声明环境变量,使后续所有 virtualenv 调用默认带回 wheel:

配置Shell / Profile
export VIRTUALENV_WHEEL=bundle
export VIRTUALENV_SETUPTOOLS=bundle
为什么virtualenv现在默认不再捆绑wheel包?
图 4:历史模式与现代解耦模式的技术特征与收益全面总结对比

总结

virtualenv 默认不再捆绑 wheel 包,是 Python 打包生态体系迈向“构建与运行严格分离”的必然结果。通过将 wheel 和构建后端隔离在瞬时沙箱中,虚拟环境得以摆脱历史遗留的工具包包袱,实现了更轻量的存储占用、更迅速的环境生成速度以及更可靠的依赖洁净度。对于普通开发者而言,这一改变无需调整日常依赖安装习惯;而在面对需要本地打包或离线构建的特定场景时,借助简单的参数或显式安装即可从容应对。

相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。