Update DiagnosticPipError to add details_link to errors#14002
Open
polkapolka wants to merge 4 commits into
Open
Update DiagnosticPipError to add details_link to errors#14002polkapolka wants to merge 4 commits into
polkapolka wants to merge 4 commits into
Conversation
polkapolka
force-pushed
the
error-details-link
branch
from
55edfb4 to
84deca7
Compare
Member
This feels... fine? I do feel like we should adopt https://diagnostic.readthedocs.io/en/latest/diagnostic.check.html eventually but not adopting it now seems fine. 😅
I suggest updating https://github.com/pypa/pip/blob/main/.readthedocs-custom-redirects.yml
Seems very reasonable to me! We can change things at a future date, if/when we migrate over to diagnostic. 😅 |
pradyunsg
reviewed
May 21, 2026
Member
pradyunsg
left a comment
pradyunsg
left a comment
There was a problem hiding this comment.
I didn't make it through everything, mostly because I'm rushing to a family thing now. 😅
| # Error Index | ||
|
|
||
| Inspired by the [Rust Compiler Error Index], this page describes the various | ||
| errors that may be presented by `sphinx-theme-builder`, indicating known causes |
Member
There was a problem hiding this comment.
Suggested change
| errors that may be presented by `sphinx-theme-builder`, indicating known causes | |
| errors that may be presented by `pip`, indicating known causes |
Comment on lines
+13
to
+19
| ## Pip Errors | ||
|
|
||
| Generic pip errors do not contain links to this page. | ||
|
|
||
| ## Diagnostic Pip Errors | ||
|
|
||
| Diagnositic pip errors contain links to this page. |
|
|
||
| **What you can do:** | ||
|
|
||
| There are three standard ways to resolve this, depending on your goal: First, use a Virtual Environment. Second, use pipx if you want to install a tool for use from the command line. Lastly, if you absolutely must install a package system-wide and understand the risks of breaking your OS, then you can bypass the check by adding the specific flag: `--break-system-packages` to the pip install command. |
Member
There was a problem hiding this comment.
Let's make this a bullet list.
|
|
||
| When pip cannot find a wheel file for a dependency, pip tries to build the wheel from the source. If building the wheel from source fails, this error is raised. | ||
|
|
||
| **What you can do:** |
Member
There was a problem hiding this comment.
nit: Add newline after, for consistency -- here, and elsewhere.
| @@ -0,0 +1 @@ | |||
| Adding a details_link to the DiagnosticPipError to link to the relevant documentation for the error. | |||
Member
There was a problem hiding this comment.
Suggested change
| Adding a details_link to the DiagnosticPipError to link to the relevant documentation for the error. | |
| Adding a link to user-facing guidance in documentation for certain error messages. |
|
|
||
| **What you can do:** | ||
|
|
||
| Clear the pip cache `pip cache purge` and then upgrade pip `pip install --upgrade pip`. Then find the path to the site-packages `python -m site` and look for folders with invalid names such as folders with `~` and delete them. |
Member
There was a problem hiding this comment.
Suggested change
| Clear the pip cache `pip cache purge` and then upgrade pip `pip install --upgrade pip`. Then find the path to the site-packages `python -m site` and look for folders with invalid names such as folders with `~` and delete them. | |
| Clear the pip cache (`pip cache purge`) and then upgrade pip (`pip install --upgrade pip`). Then find the path to the site-packages `python -m site` and delete folders with invalid names such as folders with `~`. |
Comment on lines
+81
to
+83
| Incorrect: requires = "setuptools" | ||
| Correct: requires = ["setuptools", "wheel"] | ||
|
|
Member
There was a problem hiding this comment.
Suggested change
| Incorrect: requires = "setuptools" | |
| Correct: requires = ["setuptools", "wheel"] | |
| Incorrect: `requires = "setuptools"` | |
| Correct: `requires = ["setuptools", "wheel"]` |
|
|
||
| Add the following block or equivalent to your pyproject.toml file. This tells pip to use setuptools as the default build tool: | ||
|
|
||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves #10421
Thanks @pradyunsg and @sirosen ! At the PyCon US 2026 sprints, and implementing a first pass at the feature Pradyun mentioned at the Packaging Summit. Improving the error code messages in PIP by allowing a link to documentation on pypa which can describe the context of changes and suggest potential mitigations.
There are three open questions I have from this work.
Q1: Should there be more or different testing?
Q2: Hardcoding the link to the stable readthedocs site?
Q3: Chose to add new attribute
.details_link, rather than reusing.link. Is that right?.linkis fine?Please review the descriptions of the error references on errors.md, and let me know whether my descriptions need work.