常见问题

基本

什么是包、项目或版本？

我们使用许多术语来描述 PyPI 上可用的软件，例如“项目”、“发布”、“文件”和“包”。有时这些术语令人困惑，因为它们用于在其他上下文中描述不同的事物。以下是我们在 PyPI 上使用它们的方式：

PyPI 上的“项目”是发布和文件集合的名称，以及有关它们的信息。PyPI 上的项目由 Python 社区的其他成员创建和共享，以便您可以使用它们。

PyPI 上的“发布”是项目的特定版本。例如，requests项目有许多版本，例如“requests 2.10”和“requests 1.2.1”。一个版本由一个或多个“文件”组成。

PyPI 上的“文件”，也称为“包”，是您可以下载和安装的东西。由于不同的硬件、操作系统和文件格式，一个版本可能有多个文件（包），例如包含源代码的存档或二进制轮子。

如何从 PyPI 安装文件（包）？

要了解如何从 PyPI 安装文件，请访问Python Packaging User Guide上的安装教程。

如何打包和发布我的 PyPI 代码？

有关配置、打包和分发 Python 项目的完整说明，请参阅 Python 打包用户指南中的打包教程。

什么是trove分类器？

分类器用于对 PyPI 上的项目进行分类。请参阅分类器页面以获取更多信息，以及有效分类器的列表。

什么是“猛拉”版本？

yanked 版本是安装程序始终忽略的版本，除非它是唯一与版本说明符匹配的版本（使用==或===）。有关详细信息，请参阅PEP 592。

我的帐户

为什么我需要经过验证的电子邮件地址？

目前，PyPI 需要经过验证的电子邮件地址才能执行以下操作：

• 注册一个新项目。
• 上传新版本或文件。

需要经过验证的电子邮件地址的活动列表可能会随着时间的推移而增加。

该政策将允许我们执行PEP 541中关于维护者可达性的关键政策。它还降低了垃圾邮件攻击以自动方式创建许多帐户的可行性。

您可以在帐户设置中管理您帐户的电子邮件地址。这还允许在我们开始执行此政策之前为过去注册的用户发送新的确认电子邮件。

为什么 PyPI 告诉我我的密码已泄露？

PyPI 本身并没有遭到破坏。这是一种保护措施，可降低针对PyPI及其用户的撞库攻击风险。

每次用户提供密码时——在注册、验证或更新他们的密码时——PyPI 都会安全地检查该密码是否出现在公共数据泄露中。

在每个过程中，PyPI 都会生成所提供密码的 SHA-1 哈希，并使用哈希的前五 (5) 个字符来检查Have I Been Pwned API并确定密码之前是否已被泄露。PyPI 永远不会存储明文密码或提交给 Have I Been Pwned API。

PyPI 不允许在注册时设置密码或更新密码时使用此类密码。

如果您收到一条错误消息，指出“此密码出现违规或已泄露且无法使用”，您应尽快将其更改为所有其他使用它的地方。

如果您在尝试登录或上传到 PyPI 时收到此错误，则您的密码已被重置，并且您在重置密码之前无法登录到 PyPI 。

如果我发现我的帐户有可疑活动，我应该怎么做？

所有 PyPI 用户事件都存储在帐户设置中的安全历史记录下。如果有任何看起来可疑的事件，请执行以下步骤：

• 重置你的密码
• 通过admin@pypi.org联系 PyPI 管理员以了解该事件

为什么 PyPI 告诉我我的 API 令牌已被盗用？

链接到您的帐户的 PyPI API 令牌已发布在公共网站上。它被自动撤销，但在重新生成新的之前，请检查您收到的电子邮件并尝试确定原因。可疑活动部分也适用。

什么是两因素身份验证，它如何在 PyPI 上工作？

两因素身份验证 (2FA) 通过要求两件事情来登录，使您的帐户更加安全：您知道的事情和您拥有的事情。

在 PyPI 中，“你知道的东西”是你的用户名和密码，而“你拥有的东西”可以是生成临时代码的应用程序，或安全设备（最常见的是 USB 密钥）。

强烈建议您在 PyPI 帐户上设置两个因素身份验证。

选择设置双重身份验证的用户将被要求在登录过程中提供他们的第二种身份验证方法。这仅影响通过 Web 浏览器登录，而不影响（尚未）包上传。

您可以在 Discussion.python.org 上关注2FA的改进。

使用身份验证应用程序 ( TOTP ) 的两因素身份验证如何工作？如何在 PyPI 上设置它？

PyPI 用户可以使用任何支持TOTP标准的身份验证应用程序设置双因素身份验证。

TOTP身份验证应用程序会生成一个定期更改的身份验证代码，以便在登录您的帐户时使用。

因为TOTP是一个开放标准，所以有许多应用程序与您的 PyPI 帐户兼容。流行的应用包括：

• 适用于Android或iOS 的 Google 身份验证器 （专有）
• Microsoft Authenticator（专有）
• 适用于Android或iOS 的 Duo Mobile （专有）
• 权威（专有）
• FreeOTP+（开源）
• FreeOTP（开源）

一些密码管理器（例如1Password）也可以生成验证码。出于安全原因，PyPI 仅允许您为每个帐户设置一个应用程序。

要使用身份验证应用程序设置2FA：

1. 打开身份验证 ( TOTP ) 应用程序
2. 登录到您的 PyPI 帐户，转到您的帐户设置，然后选择“使用身份验证应用程序添加2FA ”
3. PyPI 将生成一个特定于您帐户的密钥。这显示为 QR 码和文本码。
4. 使用您的身份验证应用程序扫描二维码，或手动输入。输入方法取决于您选择的应用程序。
5. 您的应用程序将生成一个身份验证代码 - 使用它来验证您在 PyPI 上的设置

PyPI 服务器和您的应用程序现在共享您的 PyPI 密钥，允许您的应用程序为您的 PyPI 帐户生成有效的身份验证代码。

下次登录 PyPI 时，您需要：

1. 照常提供您的用户名和密码
2. 打开您的身份验证应用程序以生成身份验证代码
3. 使用此代码完成登录 PyPI

使用安全设备（例如 USB 密钥）的两因素身份验证如何工作？如何在 PyPI 上设置它？

安全设备是生成一次性密码并将该密码发送到浏览器的 USB 密钥或其他设备。然后 PyPI 使用此密码来验证您作为用户的身份。

要使用USB 密钥设置两因素身份验证，您需要：

• 使用支持WebAuthn和 PublicKeyCredential的浏览器，因为这是 PyPI 实现的标准。
• 在浏览器上运行 JavaScript
• 要使用符合FIDO U2F 规范的 USB 密钥：
  • 流行的密钥包括Yubikey、Google Titan和Thetis。
  • 请注意，一些较旧的 Yubico USB 密钥不遵循 FIDO 规范，因此无法与 PyPI 一起使用

按着这些次序：

1. 登录到您的 PyPI 帐户，转到您的帐户设置，然后选择“使用安全设备（例如 USB 密钥）添加2FA ”
2. 给你的钥匙起个名字。这是必要的，因为可以向您的帐户添加多个安全设备。
3. 点击“设置安全设备”按钮
4. 按照浏览器的指示插入并触摸您的 USB 密钥

完成后，您的 USB 密钥将注册到您的 PyPI 帐户，并可在登录过程中使用。

下次登录 PyPI 时，您需要：

1. 照常提供您的用户名和密码
2. 插入并触摸您的 USB 密钥以完成登录 PyPI

我可以将哪些设备（除了 USB 密钥）用作安全设备？

符合 FIDO 的设备生态系统越来越多，因此可以与 PyPI 一起使用。

新兴解决方案包括生物识别（面部和指纹）扫描仪和 FIDO 兼容信用卡。越来越多的人支持将手机用作安全设备。

由于 PyPI 的两因素实现遵循WebAuthn标准，PyPI 用户将能够利用该领域的任何未来发展。

使用恢复代码的两因素身份验证如何工作？如何在 PyPI 上设置它？

如果您无法访问身份验证应用程序或安全设备，您可以使用这些代码登录 PyPI。

恢复代码是一次性使用。它们不能替代身份验证应用程序或安全设备，只能用于恢复。使用恢复代码登录后，它会变为非活动状态。

要提供恢复代码：

1. 登录到您的 PyPI 帐户，转到您的帐户设置，然后选择“生成恢复代码”
2. 安全存储显示的恢复代码！考虑将它们打印出来并将它们存储在安全的位置或将它们保存在密码管理器中。

如果您无法访问已存储的恢复代码或使用所有恢复代码，您可以通过在帐户设置中选择“重新生成恢复代码”来获取新代码。

要使用恢复代码登录：

1. 照常提供您的用户名和密码
2. 当提示进行两因素身份验证时，选择“使用恢复代码登录”
3. 由于每个代码只能使用一次，您可能希望将代码标记为已使用
4. 如果您剩余的恢复代码很少，您可能还需要使用帐户设置中的“重新生成恢复代码”按钮生成一组新代码。

如何使用 API 令牌通过 PyPI 进行身份验证？

在将包上传到 PyPI时，API 令牌提供了一种替代方式（而不是用户名和密码）进行身份验证。

您可以为整个 PyPI 帐户创建一个令牌，在这种情况下，该令牌将适用于与该帐户关联的所有项目。或者，您可以将令牌的范围限制为特定项目。

我们强烈建议您尽可能使用 API 令牌进行身份验证。

要制作 API 令牌：

• 验证您的电子邮件地址（检查您的帐户设置）
• 在您的帐户设置中，转到 API 令牌部分并选择“添加 API 令牌”

要使用 API 令牌：

• 将您的用户名设置为__token__
• 将密码设置为令牌值，包括pypi-前缀

您在哪里编辑或添加这些值取决于您的个人用例。例如，一些用户可能需要编辑他们的.pypirc文件，而其他用户可能需要更新他们的 CI 配置文件（例如.travis.yml，如果您使用 Travis）。

高级用户可能希望通过使用 base64 对其进行解码来检查其令牌，并根据 PyPI 上显示的唯一标识符检查输出。

为什么某些操作需要我确认密码？

PyPI 要求您在执行敏感操作之前确认您的密码。敏感操作包括添加或删除维护者、删除分发、生成 API 令牌和设置双因素身份验证等。

如果您上次确认密码已超过一个小时，您只需重新确认密码即可。

我们强烈建议您仅在受密码保护的个人计算机上执行此类操作。

如何更改我的 PyPI 用户名？

PyPI 目前不支持更改用户名。

相反，您可以使用所需的用户名创建一个新帐户，将新帐户添加为旧帐户拥有的所有项目的维护者，然后删​​除旧帐户，这将具有相同的效果。

整合

PyPI 有我可以使用的 API 吗？

是的，包括新软件包和新版本的 RSS 提要。请参阅 API 参考。

如何运行 PyPI 的镜像？

如果你需要运行自己的 PyPI 镜像，bandersnatch 项目是推荐的解决方案。请注意，PyPI 镜像的存储需求将超过 1 TB，而且还在不断增长！

当项目的新版本发布时，我如何获得通知？

您可以订阅项目发布的 RSS 提要。此外，还有一些第三方服务可以为列为GitHub 应用程序的项目发布和漏洞提供全面的监控和通知。

我在哪里可以看到有关 PyPI、下载和项目/包使用情况的统计信息？

您可以通过我们在 Google BigQuery 上的公共数据集分析 PyPI 项目/包元数据并下载使用统计信息。

Libraries.io 提供 PyPI 项目（例如API ）的统计信息，包括 GitHub 星号和分叉、依赖跟踪（正在进行中）和其他相关因素。

有关正常运行时间和性能的最新统计信息，请参阅我们的状态页面。

PyPI 项目管理

如何将我的私有包发布到 PyPI？

PyPI 不支持发布私有包。如果您需要将私有包发布到包索引，推荐的解决方案是运行您自己的devpi 项目部署。

为什么我想要的项目名称不可用？

您的发布工具可能会返回一个错误，即您的新项目无法使用您想要的名称创建，尽管在 PyPI 上没有同名项目或版本的证据。目前，出现这种情况的主要原因有四个：

• 项目名称与从 2.5 到现在的任何主要版本的Python 标准库模块冲突。
• 项目名称与现有项目过于相似，可能容易混淆。
• PyPI 管理员已明确禁止该项目名称。例如，pip install requirements.txt是一个常见的拼写错误pip install -r requirements.txt，不应该让用户对恶意包感到惊讶。
• 项目名称已被其他用户注册，但尚未创建任何版本。请参阅如何声明已放弃或以前注册的项目名称？

如何申请废弃或之前注册的项目名称？

遵循PEP 541的“如何请求名称转移”部分。

PyPI 上的项目有哪些协作者角色？

合作者有两种可能的角色：

维护者：可以上传包的版本。无法添加协作者。无法删除文件、版本或项目。

所有者：可以上传版本。可以添加其他合作者。可以删除文件、发布或整个项目。

如何成为 PyPI 项目的所有者/维护者？

只有项目的当前所有者才能添加新的所有者或维护者。如果您需要申请所有权，您应该直接联系项目的当前所有者。许多项目所有者在项目页面的“元”详细信息的“作者”字段中提供了他们的联系方式。

如果所有者没有回应，请参阅如何声明已放弃或之前注册的项目名称？

如何上传不同格式的项目描述？

默认情况下，上传的描述将使用reStructuredText呈现。如果描述是像 Markdown 这样的替代格式，包可以将long_description_content_typein设置setup.py为替代格式。

有关可用格式的详细信息，请参阅Python 打包用户指南。

有关如何检查描述的有效性，另请参阅：为什么我收到“描述无法呈现”错误？

如何为我的项目获得文件大小限制豁免或增加？

如果您因为达到上传文件大小限制而无法将项目的发布上传到 PyPI，我们有时可以增加您的限制。确保您已为该项目上传了至少一个版本，该版本低于限制（开发版本号可以）。然后，提出问题并告诉我们：

• PyPI（或测试 PyPI）上的项目链接
• 发布的大小，以兆字节为单位
• 您需要增加哪些索引（PyPI、Test PyPI 或两者）
• 对您的项目的简要描述，包括增加大小的原因。

如何为我的项目获得总项目规模限制豁免或增加？

如果您因为达到项目大小限制而无法将项目的发布上传到 PyPI，请首先删除所有不必要的发布或单个文件以降低整体项目大小。

如果这不可能，我们有时可以提高您的限额。提出问题并告诉我们：

• PyPI（或测试 PyPI）上的项目链接
• 项目的总大小，以 GB 为单位
• 对您的项目的简要描述，包括增加大小的原因。

PyPI 从哪里获取有关项目漏洞的数据，我该如何纠正它？

PyPI 从Open Source Vulnerabilities 项目 接收关于托管在其上的包中的漏洞的报告，该项目反过来从Python Packaging Advisory Database中获取漏洞。

如果您认为项目的漏洞数据无效或不正确，请提交包含详细信息的问题。

故障排除

为什么我收到“描述无法呈现”错误？

如果包描述无法呈现，PyPI 将拒绝上传。您可以使用 twine 的 check 命令在本地检查描述的有效性。

我忘记了我的 PyPI 密码。你能帮助我吗？

如果您忘记了您的 PyPI 密码，但您记得您的电子邮件地址或用户名，请按照以下步骤重置您的密码：

1. 去重设你的密码。
2. 输入您用于 PyPI 的电子邮件地址或用户名并提交表单。
3. 您将收到一封包含密码重置链接的电子邮件。

我无法访问我的 PyPI 帐户。你能帮助我吗？

如果您因以下原因而无法访问您的 PyPI 帐户：

• 无法访问与您的帐户关联的电子邮件地址
• 丢失两因素身份验证应用程序、设备和恢复代码

您可以继续在我们的跟踪器上提出问题，以请求有关帐户恢复的帮助。

为什么我会收到“无效或不存在的身份验证信息”。上传文件时出错？

如果您使用用户名和密码进行上传：

1. 确保您的用户名和密码正确。
2. 确保您的用户名和密码不包含任何尾随字符，例如换行符。

如果您使用API 令牌进行上传：

1. 确保您的 API 令牌有效且未被撤销。
2. 确保您的 API 令牌格式正确并且不包含任何尾随字符，例如换行符。

在这两种情况下，请记住 PyPI 和 TestPyPI 都需要您创建一个帐户，因此您的凭据可能不同。

如果您使用 Windows 并尝试将密码或令牌粘贴到命令提示符或 PowerShell 中，请注意 Ctrl-V 和 Shift+Insert 不起作用。相反，您可以使用窗口菜单中的“编辑 > 粘贴”，或在“属性”中启用“使用 Ctrl+Shift+C/V 作为复制/粘贴”。这是Python模块 的一个已知问题。getpass

为什么我在 期间收到“未找到匹配的发行版”或“无法获取 URL”错误pip install？

传输层安全性或 TLS 是我们确保您的计算机和 PyPI 之间的连接是私密和安全的一部分。它是一种加密协议，随着时间的推移有多个版本。PyPI在 2018 年 4 月关闭了对 TLS 版本 1.0 和 1.1的支持。在 PSF 博客上了解原因。

如果您遇到问题pip install并遇到错误No matching distribution found，请Could not fetch URL尝试添加-v到命令以获取更多信息：

pip install --upgrade -v pip

There was a problem confirming the ssl certificate如果您看到类似ortlsv1 alert protocol version或的错误TLSV1_ALERT_PROTOCOL_VERSION，您需要使用更新的 TLS 支持库连接到 PyPI。

您需要采取的具体步骤取决于您的操作系统版本、您的 Python 安装来源（python.org、您的操作系统供应商或中间分销商）以及已安装的 Python、.setuptools和pip.

如需帮助，请访问Libera 上的#pypaIRC 频道，在pypa/packaging-problems/issues 提交问题，或在 Discourse 上讨论，包括您的操作系统和安装详细信息以及pip install --upgrade -vvv pip.

我在使用 PyPI 网站时遇到问题。你能帮助我吗？

我们非常重视可访问性，并希望让每个人都能轻松使用该网站。

如果您遇到可访问性问题，请在 GitHub 上向我们报告，以便我们尝试为您和其他人解决问题。

为什么我不能通过浏览器界面手动将文件上传到 PyPI？

在之前的 PyPI 版本中，维护人员曾经可以使用 Web 浏览器中的表单将发布版本上传到 PyPI。新版本的 PyPI 已弃用此功能 - 我们建议您使用 twine 将项目上传到 PyPI。

为什么我的包裹或用户注册被阻止了？

垃圾邮件发送者定期返回 PyPI，希望将他们的搜索引擎优化的网络钓鱼、诈骗和点击农场内容放在网站上。由于 PyPI 允许对长描述和其他与项目相关的数据进行索引，并且具有普遍可靠的搜索声誉，因此它是主要目标。

当 PyPI 管理员被垃圾邮件淹没或确定 PyPI 存在其他威胁时，可能会禁用新用户注册和/或新项目注册。查看我们的状态页面以获取更多详细信息，因为我们可能会更新它并说明干预的原因。

为什么我收到“文件名或内容已存在”或“文件名已被使用”错误？

PyPI 将由于以下原因之一返回这些错误：

• 文件名已被使用且文件存在
• 文件名已被使用，但文件不再存在
• 存在内容完全相同的文件

PyPI 不允许重用文件名，即使项目已被删除并重新创建。

为避免这种情况，请先使用 Test PyPI 执行并检查您的上传，然后再上传到pypi.org。

如何请求新的 trove 分类器？

如果您想请求新的 trove 分类器文件，请在pypa/trove-classifiers项目上提出拉取请求。一定要简要说明为什么它很重要。

我在哪里可以报告错误或提供有关 PyPI 的反馈？

如果您遇到 PyPI 本身的问题，我们欢迎通过我们的问题跟踪器提供建设性反馈和错误报告。请注意，此跟踪器仅适用于运行 PyPI 的软件的问题。在编写新问题之前，首先检查是否不存在类似问题。

如果您遇到的问题是从 PyPI 安装的特定包，您应该直接联系该项目的维护者。

关于

谁维护 PyPI？

PyPI 由 Warehouse 项目提供支持；Warehouse是一个在 Python Packaging Authority (PyPA) 的保护下开发并得到 Python Packaging Working Group (PackagingWG) 支持的开源项目。

PyPA是一个独立的开发人员团体，其目标是改进和维护许多与 Python 打包相关的核心项目。

PackagingWG是 Python 软件基金会 (PSF) 的一个工作组，其目标是筹集和支付资金以支持 Python 打包的持续改进 。最近，它获得了开放技术基金的奖励，该基金的资金使开发人员能够提高 Warehouse 的安全性和可访问性。

PyPI 的动力是什么？

PyPI 由Warehouse以及我们慷慨的赞助商提供的各种工具和服务提供支持。

我可以依赖 PyPI 可用吗？

截至 2018 年 4 月 16 日，PyPI.org 处于“生产”状态，这意味着它已退出测试版并替换了旧站点 (pypi.python.org)。它现在是健壮的、经过测试的，并为预期的浏览器和 API 流量做好了准备。

由于我们的赞助商Fastly ， PyPI 通过CDN进行了大量缓存和分发，因此在全球范围内普遍可用。但是，该站点主要由志愿者维护，我们不提供任何特定的服务水平协议，并且正如对于一个巨大的分布式系统所预料的那样，事情可能而且有时确实会出错。有关当前和过去的中断和事件，请参阅我们的状态页面。如果您对包索引有高可用性要求，请考虑使用镜像或私有索引。

我如何为 PyPI 做贡献？

为了继续维护和改进 PyPI（也称为仓库项目） ，我们还有大量工作要做。

财务：我们非常感谢您为开发和维护提供资金。

开发： Warehouse 是开源的，我们希望看到一些新面孔参与该项目。您无需成为经验丰富的开源开发人员即可做出贡献——事实上，我们很乐意帮助您提出您的第一个开源拉取请求！

如果您具备 Python、ElasticSearch、HTML、SCSS、JavaScript 或 SQLAlchemy 方面的技能，请浏览我们的“入门”指南，然后查看问题跟踪器。我们创建了一个“好的第一期”标签——我们建议您从这里开始。

问题被分组为里程碑；解决当前里程碑中的问题是帮助推动项目向前发展的好方法。如果您对处理特定问题感兴趣，请发表评论，我们可以指导您完成投稿过程。

保持更新： 您还可以在 Discourse 上的 Python 打包论坛上关注项目的持续开发。

如何跟上 PyPI 即将发生的变化？

PyPI 的更改通常在pypi-announce 邮件列表和PSF 博客上以“pypi”标签发布。PSF 博客也有用于“pypi”标签的 Atom和RSS提要。

如何获取 PyPI 的 IP 地址列表？

所有流量都通过我们的全球 CDN 进行路由，该 CDN 在此处列出了它们的公共 IP 地址：https ://api.fastly.com/public-ip-list 。

可以在此处找到有关此列表的更多信息：https ://docs.fastly.com/en/guides/accessing-fastlys-ip-ranges 。

“测试版功能”徽章是什么意思？Warehouse 当前的测试版功能是什么？

当 Warehouse 的维护人员部署新功能时，首先我们用一个小的“beta 功能”符号标记它们，以告诉您：这应该可以正常工作，但它是新的并且比其他站点功能测试更少。

目前，没有任何功能处于测试阶段。

我如何发音“PyPI”？

“PyPI”应该发音为“pie pea eye”，特别是“PI”发音为单个字母，而不是单个声音。这最大限度地减少了与PyPy项目的混淆，后者是 Python 语言的流行替代实现。