注意

本节文档目前正在编写中。pip 开发人员欢迎您帮助完成这些文档。如果您有兴趣帮忙，请在 跟踪问题 中告知我们，或直接提交一个拉取请求并在该跟踪问题中提及。

问题分类

本节介绍了 pip 中的 issue 跟踪以及如何帮助对报告的 issue 进行分类。

问题追踪器

该 pip 问题追踪器 与项目一起托管在 GitHub 上。

目前，问题追踪器用于错误、功能请求和一般用户支持。

在 pip 问题追踪器中，我们使用标签和里程碑来组织和跟踪工作。

标签

问题标签用于

  1. 对问题进行分类

  2. 为贡献者和报告者提供状态信息

  3. 帮助贡献者找到要完成的任务

当前的标签集分为几个类别，由前缀标识

C - 类别

与功能请求或问题相关的 pip 功能区域

K - 种类 O - 操作系统：针对操作系统特定的问题

P - 项目/平台

与 pip 外部的某些内容相关

R - 解决方法

不再需要任何讨论，已确定了行动，并且问题正在等待或已关闭

S - 状态

用于一些自动标签和其他指示需要工作的信息

类型

问题的作用或类型

每个类别的具体标签都有一个描述，可以在 标签 页面上看到。

此外，还有一些独立标签

good first issue

此标签将问题标记为初学者友好，并在 GitHub 为首次访问存储库的访问者显示的横幅中显示

triage

创建问题时给出的默认标签

trivial

用于移除 新闻文件要求 的拉取请求的特殊标签

needs rebase or merge

这是一个特殊标签，由 BrownTruck 用于标记具有合并冲突的 PR

自动化

有几个助手来管理问题和拉取请求。

在问题追踪器上创建的问题会自动由 triage-new-issues 机器人添加 triage 标签。当添加另一个标签时，该标签将自动删除。

当一个问题需要作者的反馈时，我们可以用 S: awaiting response 标记它。当作者回复时，no-response 机器人会删除该标签。

在问题关闭 30 天后，lock 机器人会锁定问题并添加 S: auto-locked 标签。这使我们能够避免监控现有的已关闭问题，但不幸的是会阻止并阻止对已关闭问题的引用显示为链接。

分类问题

用户可以出于多种原因提出问题

  1. 关于可以添加或改进的 pip 功能的建议

  2. 使用 pip 时遇到的问题

  3. 关于 pip 可用性的担忧

  4. 需要使用 pip 解决的一般打包问题

  5. 安装或使用 Python 包时遇到的问题

  6. 管理虚拟环境时遇到的问题

  7. 管理 Python 安装时遇到的问题

对问题进行分类意味着要确定正在发生的问题类型，以及

  • 确认错误

  • 提供支持

  • 讨论和设计工具的用途

具体来说，要解决问题

  1. 阅读问题标题

  2. 浏览问题描述

  3. 提问

  4. 如果有时间，尝试重现

  5. 搜索或记住相关问题，并链接到它们

  6. 确定适当的关注领域（如果适用）

请记住，所有交流都与其他人进行，应根据 行为准则 进行。

问题的生命周期（错误或支持）通常看起来像

  1. 等待分类（用标签 triage 标记）

  2. 确认问题 - 与用户进行一些讨论，收集详细信息，尝试重现问题（可能用特定的类别、S: awaiting-response、S: discussion-needed 或 S: need-repro 标记）

  3. 已确认 - 该问题在简单的方式下能够始终如一地重现，或者已确定了可能导致该问题的机制

  4. 等待修复 - 修复已确定，并且不再需要对该问题的任何真正讨论，应标记为 R: awaiting PR

  5. 已关闭 - 可能由于多种原因

    • 已修复

    • 无法重现，无法获得更多详细信息，也无法取得进展

    • 实际问题出在另一个项目上，或者与系统配置相关，pip 无法（或将不会）为此进行调整

请求信息

请求更多信息以更好地了解导致问题的上下文和环境。具体信息的示例，这些信息可能在不同的情况下很有用

  • pip debug: pip debug

  • pip 版本: pip -V

  • Python 版本: python -VV

  • Python 路径: python -c 'import sys; print(sys.executable)'

  • python 在 PATH 上: Unix: which python; Windows: where python

  • shell 解析的 Python: type python

  • pip 的来源（get-pip.py、操作系统级包管理器、ensurepip、手动安装）

  • 使用虚拟环境（使用 --system-site-packages？）

  • 使用 conda 环境

  • PATH 环境变量

  • 网络状况（例如，隔离环境、防火墙）

  • --verbose 失败命令的输出

  • (Unix) strace 失败命令的输出（注意不要将输出到正在安装的包所在的同一个目录中，否则 pip 会永远循环复制日志文件……）

  • (Windows) procmon 失败命令期间的输出 (示例请求)

  • 与问题相关的文件的列表（例如，ls -l venv/lib/pythonX.Y/problem-package.dist-info/）

  • 意外行为是否曾经按预期工作过 - 如果是，那么设置的详细信息是什么（与上述信息相同）

一般来说，如果可以帮助确认或排除可能的错误源，则请求信息是好的。我们不应该请求无法提高我们对情况理解的信息。

重现问题

无论何时发生问题，并且原因不明确，我们必须能够独立重现它。这有几个目的

  1. 如果是 pip 问题，则任何修复都需要测试 - 一个好的重现方法可以帮助实现这一点。

  2. 如果使用提供的说明无法重现问题，这有助于排除许多可能的原因。

  3. 清晰的说明是与报告问题的人员达成一致的简单方法。

重现问题的最佳方法是使用脚本。

脚本可以复制到文件并执行，而 shell 输出必须逐行手动复制。

用于重现问题的脚本应该

  • 可移植性 (对系统几乎没有/没有假设，除了它适用的是 Unix 或 Windows)

  • 非破坏性

  • 方便

  • 需要运行者进行很少/无需设置

示例

  • 创建和安装具有不同版本的多个轮子 (链接)

  • 使用小型 Web 服务器进行身份验证错误 (链接)

  • 使用 Docker 测试系统或全局配置相关问题 (链接)

  • 使用 Docker 测试特殊文件系统权限/配置 (链接)

  • 使用 Docker 进行带有 get-pip 的全局安装 (链接)

  • 在没有 /usr/lib64 的系统上使用 get-pip (链接)

  • 使用当前开发分支中的 pip 进行重现 (链接)

达成解决

一些用户支持问题更多地与系统配置有关，而不是 pip。重要的是，要以与其他问题相同的谨慎和关注来处理这些问题，特别是

  1. 除非问题很旧并且用户似乎不活跃，否则在关闭问题之前等待确认

  2. 引导用户到最适合他们问题的论坛

  3. 仅仅因为用户支持问题最适合在其他论坛上解决，并不意味着我们不能使事情变得更容易。尝试从用户的查询中提取和理解如何使他们或您更容易，例如通过更好的警告或错误消息。如果不存在涵盖该情况的问题，则创建一个。如果存在问题，请确保在关闭此问题之前引用该问题。

  4. 用户可能在安装包时遇到问题，其中包的 setup.py 或构建后端配置非常复杂。在这些情况下，我们可以帮助进行故障排除，但最佳建议是将他们引导到相关项目的支持渠道。

  5. 不要急于假设它是一个原因或另一个原因。看起来像别人的问题仍然可能是 pip 中的问题，或者至少是可以改进的地方。

  6. 关于 Python 打包的常规讨论

关闭问题

当问题被认为已解决并关闭时

  • 对于问题讨论中代表的每个可能的改进或问题

    • 已就特定行动达成一致，并且行动似乎在项目之外，之后项目中无需任何后续行动。

      • PEP 更新（在 python/peps 中有相应的问题）

      • 由另一个问题跟踪

    • 已识别出特定于项目的错误，并且该错误在主分支的最新提交中不再出现。

  • 一项增强或功能请求不再有支持者，并且维护人员认为不值得保持开放。

  • 已识别出问题是重复的，并且它确实是重复的（即原始报告非常好，并直接指向问题）

  • 问题已解决，并且可以独立验证不再是问题。如果这是代码，则应识别和发布导致该问题的特定更改/PR 以进行跟踪。

常见问题

  1. 与网络相关的問題 - 任何涉及重试、地址查找或类似内容的问题通常都是网络问题。

  2. 与拥有多个 Python 版本或 OS 包管理器管理的 pip/python 安装（特别是与 Debian/Ubuntu 一起）有关的问题。这些问题通常表现为

    1. 无法找到已安装的包

    2. 无法找到基本库，缺少基本的操作系统组件

    3. 在这些情况下，您需要确保我们知道他们是如何获得 Python 和 pip 的。了解相关的包管理器命令会有所帮助，例如 dpkg -S。

对于由重新分发者更改引起的问题

某些问题是由 Python/pip 的重新分发者对 Python/pip 做出的修补程序引起的。

某些重新分发者已共享首选措辞，以将用户重定向到他们的问题跟踪器。

Fedora、RHEL、CentOS（以及其他衍生版本 - Rocky、Scientific、CloudLinux）

This issue looks like it's caused by changes that Fedora or Red Hat
made in their pip packaging. Please file a Fedora bug at
https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=python-pip

cc @encukou @hroncok

Debian

This issue looks like it's caused by changes that Debian made in
their pip packaging. Please file a bug with Debian, with
`reportbug python3-pip` [Docs](https://www.debian.org/Bugs/Reporting).
You can link to this issue in your bug report.

In the meantime, you may be able to work-around your issue by upgrading
pip inside your virtualenv: `python -m pip install -U pip`

Ubuntu

This issue looks like it's caused by changes that Ubuntu made in
their pip packaging. Please file a bug with Ubuntu, with
`ubuntu-bug python3-pip` [Docs](https://help.ubuntu.com/community/ReportingBugs).
You can link to this issue in your bug report.

In the meantime, you may be able to work-around your issue by upgrading
pip inside your virtualenv: `python -m pip install -U pip`