Python第三方库构建工具术语:pip、setuptools与distutils的角色

何川
何川
发布时间:2026-11-22 | 13人浏览过
原创

深入解析Python打包生态中核心工具的角色定位与协同原理:pip如何作为构建前端负责依赖解析与安装,setuptools如何作为构建后端组织代码与生成分发包,以及distutils为何走向弃用与移除。

一、核心定义与分工边界:前端、后端与历史遗留

现代 Python 打包标准(基于 PEP 517/518)将“安装”与“构建”做出了严格解耦。理解这三者的第一步,是明确它们在软件分发生态中所处的位置:

  • pip(Build Frontend / Package Installer): 客户端工具。它不直接负责把 Python 脚本编译或打包成压缩包,而是负责环境依赖解析、从 PyPI 仓库下载对应版本的分发文件、创建隔离构建环境,并在最后把文件解压放置到 Python 环境的 site-packages 目录中。
  • setuptools(Build Backend / Packaging Tooling): 构建系统。当一个库只有源码(包含 setup.py 或 pyproject.toml)而没有预编译二进制文件时,pip 会调用 setuptools 来编译 C/C++ 扩展、扫描包内模块、收集静态资源,最终输出符合规范的 .whl(Wheel)或 .tar.gz(sdist)分发物。
  • distutils(Legacy Standard Library Module): 历史产物。它自 2000 年(Python 1.6/2.0)加入 Python 标准库,最初奠定了 setup.py 的基础语法。但因为作为标准库内置,其更新周期与 Python 解释器强绑定,无法适应现代开源社区快速迭代的需求。setuptools 最初就是为了补充 distutils 的不足而诞生的扩展层。
Python第三方库构建工具术语:pip、setuptools与distutils的角色
图 1:Python 打包生态中 pip、setuptools 与 distutils 的角色分工与协作关系

二、从源码到安装:构建工具的完整执行流程

为了直观感受 pip 和 setuptools 的配合,我们可以看一下执行 pip install some-package 时,底层究竟发生了什么。

在 PyPI 上,开发者通常会上传两种形态的发布包:

  1. Wheel 包(.whl):预构建的分发包。Wheel 包含了已经组织好的文件目录以及编译好的机器码(如果有 C 扩展)。对于这类包,pip 下载后只需解包并将文件拷贝到目标目录,不需要构建后端介入。
  2. 源码包(sdist,通常为 .tar.gz):只包含原始代码、构建脚本和配置。此时 pip 必须借助构建后端将其转化为 Wheel。

在现代 PEP 517 规范下,当 pip 遇到源码包时,会经历以下标准化步骤:

  1. 读取配置文件:pip 解压源码包,检查根目录下的 pyproject.toml。如果声明了 build-backend = "setuptools.build_meta",pip 就明确知道本次构建应使用 setuptools。
  2. 创建隔离构建环境:pip 会在临时目录中启动一个沙盒环境,仅安装构建所需的依赖(例如 setuptools 和 wheel),杜绝本地全局环境对打包过程的干扰。
  3. 调用后端生成 Wheel:pip 调用 setuptools 的标准接口方法 build_wheel()。setuptools 启动编译,生成规范的 .whl 文件。
  4. 交付与部署:setuptools 将生成的 Wheel 文件交回给 pip,pip 将其解压安装至当前 Python 环境的 site-packages,最后清理临时构建环境。
Python第三方库构建工具术语:pip、setuptools与distutils的角色
图 2:Python 库在开发者构建分发与终端用户安装时的完整执行步骤

三、distutils 为何被弃用并彻底移除?

在很多较旧的教程或遗留代码中,经常能看到 from distutils.core import setup。然而在较新的 Python 3.12+ 环境下运行这类代码,会直接遭遇 ModuleNotFoundError。了解这一演进过程有助于理解现代工具的设计初衷。

1. 标准库的“双刃剑”效应

distutils 在 2000 年被纳入 Python 标准库,这一举措在当时极大地统一了 C 扩展模块的编译方式。但随着 Python 生态爆发式增长,它暴露出致命缺陷:

  • 更新周期僵化:作为内置模块,distutils 的任何 Bug 修复和新特性都必须等待 Python 新的小版本甚至次版本发布才能推送给用户。
  • 功能停滞不前:distutils 甚至不支持依赖声明(无法表达“本包依赖 requests >= 2.0”),也不支持卸载已安装的包。

2. setuptools 的崛起与双轨并存

为了打破这个僵局,社区推出了第三方库 setuptools。setuptools 早期采用了“猴子补丁(Monkey Patch)”和深度继承 distutils 的方式来扩展功能,引入了依赖管理、自动发现包以及早期的 easy_install 工具。

这导致很长一段时间内,系统里存在“双份”构建逻辑:Python 解释器自带一个老态龙钟的 distutils,而用户通过 pip 更新的 setuptools 内部又包了一层经过魔改的 distutils。两者在不同环境下的行为差异,引发了大量难以调试的编译错误与路径冲突。

3. PEP 632 与彻底退役

为了从根本上理清包构建体系,Python 官方通过了 PEP 632,正式敲定了 distutils 的退役路线:

  • Python 3.10(2021 年):distutils 被正式标记为弃用(Deprecated),导入时会触发 DeprecationWarning。同时 setuptools 全面内置了自身的替代实现。
  • Python 3.12(2023 年):distutils 从标准库源代码中被彻底删除。任何依赖 import distutils 的第三方库如果未做适配,将直接报错。
Python第三方库构建工具术语:pip、setuptools与distutils的角色
图 3:Python 打包工具生态的历史演进与 distutils 的退役历程

四、现代构建体系(PEP 517/518)与选择指南

在过去,Python 构建包几乎只有一种方式:在项目根目录写一个 setup.py,然后直接运行 python setup.py sdist bdist_wheel。

但这种传统方式存在一个无法克服的悖论——“先有鸡还是先有蛋”: setup.py 本身是一个可执行的 Python 脚本,如果构建该脚本依赖了特定版本的 setuptools 或 Cython,用户在没有安装这些前置依赖时,连执行 setup.py 解析元数据都做不到。

为了彻底解决这个问题,Python 社区推出了 PEP 518(声明构建依赖) 与 PEP 517(统一构建后端接口),正式确立了以 pyproject.toml 为核心的声明式标准。

现代构建配置示例:pyproject.toml

现在的 Python 项目推荐使用声明式的 pyproject.toml 文件,清晰交代构建后端与项目元数据,不再强求编写动态的 setup.py:

[build-system]
# 明确声明构建当前项目所需的工具,pip 会在构建前自动安装它们
requires = ["setuptools>=61.0", "wheel"]
# 指定构建后端入口
build-backend = "setuptools.build_meta"

[project]
name = "my_custom_package"
version = "0.1.0"
description = "A modern Python library example"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
]

借助这套机制,构建生态变得完全开放:后端不仅可以是 setuptools,还可以是轻量级的 flit-core、注重锁文件管理的 poetry-core,或是高性能的 hatchling。而无论后端怎么换,用户端的 pip install 体验和接口完全保持一致。

Python第三方库构建工具术语:pip、setuptools与distutils的角色
图 4:现代 Python 打包工具的角色、职责边界与选型决策矩阵

五、避坑清单:开发与部署中的注意事项

1. 避免直接运行 python setup.py install

传统的 python setup.py install 不具备依赖解析沙盒机制,容易产生没有安装清单的半成品文件,甚至破坏当前环境中的依赖树。现代标准中,即使在本地调试源码,也应当使用 pip install . 或可编辑安装 pip install -e .。

2. 遇到 No module named 'distutils' 的正确修复姿势

如果你在 Python 3.12+ 运行老旧项目时遇到此报错:

  • 第一优先级:更新该项目的第三方依赖库到最新版本(新版本通常已移除了对 distutils 的依赖);
  • 第二优先级:安装或升级 setuptools(pip install --upgrade setuptools),某些兼容补丁库能自动重定向内部调用;
  • 改动自身代码:将源码中的 from distutils.core import setup 修改为 from setuptools import setup。
3. 构建发包请认准标准前端 build

官方现在推荐使用独立的构建工具包 build(pip install build),运行 python -m build。它会自动读取 pyproject.toml 并调用声明的构建后端(如 setuptools),生成规范的 Wheel 和源码压缩包。

相关专题:

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表