PyPI 对上传分发的更严格检查

过去几个月里,PyPI 增加了一些额外的检查,可以拒绝上传的源码分发(“sdists”)和构建分发(“bdists”或“wheels”)。
这些检查是一项更大计划的一部分,该计划旨在让 Python 打包生态系统更能抵御解析器差异,后续还会增加更多检查,目标是让 PyPI 对分发的处理不那么宽松,并且更严格地符合各自的规范。
对于下游用户(包的使用者)来说,这些变化没有破坏性影响。遇到失败的包维护者应确保自己使用的是非 EOL 版本的 Python,以及能够生成符合打包标准的分发的构建后端。
背景¶
Python 打包有两种主要的分发格式:
- 源码分发,即 sdists。它们以压缩 tar 归档(“tarballs”)的形式分发,后缀为 .tar.gz。
- 构建分发,即 bdists(或 wheels)。它们以 ZIP 归档的形式分发,后缀为 .whl。
tar 和 ZIP 在设计时都不是为了承担它们在 Python 打包中的角色1:两者都包含与 Python 包分发无关的元数据,并且周围环绕着一个对输入解释十分宽松的解析器生态系统。
这种宽松在本地用户环境中通常是正确的,因为用户常常希望从损坏或轻微不正确的归档中恢复重要数据。
然而,在网络环境中,尤其是在打包环境中,这种宽松是不正确的:即使是彼此独立的宽松实现之间在解析上的微小差异,也可能导致解析器差异,从而使相同的输入在不同平台和不同工具下解压出不同的结果。
原则上,攻击者可以利用这些差异来破坏 Python 打包(以及最终用户)所假定的许多性质,包括:
- PyPI 自身对每个上传分发的解析(包括依赖等重要元数据)与每个安装器看到的内容一致;
- 第三方(如镜像和安全扫描器)所“看到”的分发内容与 PyPI 看到的一致;
- 像 pip install ... 和 uv add ... 这样的调用会产生相同的安装状态。
违反这些性质可能导致用户安装看起来合法但实际恶意的分发,即使该分发自身的完整性(例如通过哈希)已经得到确认。
变更¶
在过去几周里,PyPI 已开始拒绝:
- 使用“V7”风格 tar 归档的源码分发。V7 是一种遗留的、基本未被规范化的 tar 格式,源自 UNIX V7,从未由 Python 自带的 tarfile 模块生成过。
- 包含可能在归档层面被误解为 ZIP 控制结构的 ZIP 注释的构建分发。
这些变更建立在 Seth Larson 去年八月专门为减少 ZIP 差异所做工作的基础之上。
这对我来说意味着什么?¶
如果你是 Python 打包的下游用户:没什么!这些变更不会直接影响你,你已经依赖的任何分发(通过 pip install 或 uv add 安装)都会继续正常工作。
如果你是包维护者:大概也没什么。PyPI 上绝大多数源码分发不受这些变更影响,因为它们已经符合 pax 要求。
如果你是维护者,并且确实因归档格式原因遇到上传被拒绝,请查阅 PyPI 的归档文档。随着我们逐步收紧对格式错误或不符合规范的上传的限制,PyPI 将努力保持该页面为最新状态。
对许多维护者来说,修复方法会很直接:
像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。在回复和工具调用中都要原样使用它们:它们会在任何内容运行之前被填入真实值。不要要求验证它们,也不要用示例替换它们。
- 确保你的分发包(包括 sdists 和 bdists)是用 Python 构建后端构建的,而不是通过手动用 tar、zip 或类似工具打包归档。流行的构建后端通常既符合分发包格式规范,也符合 PyPI 的附加归档限制。
- 如果你无法从手动打包步骤迁移出去,请确保你手动符合归档要求,即:源码分发包必须是 POSIX pax 风格的 tar 归档。如果你使用 GNU tar,你需要传入 --format=pax 来覆盖默认值。此外,源码分发包必须避免某些 tar 特性,即使它们可以封装在符合 pax 的 tar 中。这些包括“sparse”成员和 pax 供应商扩展。构建分发包必须是有效的 ZIP 归档。两种格式都要求其成员使用 UTF-8 编码的文件名。
如果你无法从手动打包步骤迁移出去,请确保你手动符合归档要求,即:
- 源码分发包必须是 POSIX pax 风格的 tar 归档。如果你使用 GNU tar,你需要传入 --format=pax 来覆盖默认值。此外,源码分发包必须避免某些 tar 特性,即使它们可以封装在符合 pax 的 tar 中。这些包括“sparse”成员和 pax 供应商扩展。
源码分发包必须是 POSIX pax 风格的 tar 归档。如果你使用 GNU tar,你需要传入 --format=pax 来覆盖默认值。
- 此外,源码分发包必须避免某些 tar 特性,即使它们可以封装在符合 pax 的 tar 中。这些包括“sparse”成员和 pax 供应商扩展。
- 构建分发包必须是有效的 ZIP 归档。
- 两种格式都要求其成员使用 UTF-8 编码的文件名。
下一步是什么?¶
这是一项持续进行的倡议,涉及 Python 生态系统的多个方面。我们的目标是将这项工作与 Python 本身(通过减少 Python 自有的 zipfile 和 tarfile 中的差异数量)以及 Python 打包标准(通过进一步约束和提高分发包规范的精确性)保持一致。
未来,PyPI 将继续识别可应用于上传的分发包的新限制。我们的目标是识别最小干扰的限制,即那些可以在不破坏(几乎)任何用户的情况下实施的限制。归档差异绝大多数利用了归档格式中晦涩或未使用的方面,因此这通常是可行的。
短期内,PyPI 将评估以下附加限制:
- 完全拒绝 GNU 风格的 tar 归档。源码分发包规范已经禁止这些,但由于维护者的非平凡使用,目前是允许的。关于此事的初步计划见 #21012。
- 完全拒绝 ZIP 注释。PyPI 已经拒绝了许多形式的这些,但允许一小部分,以兼容那些在归档注释中放入无害消息(如版本号)的 ZIP 编码器。关于此事的初步计划见 #20934。
- 在众多其他打包生态系统中。↩