Question
Choosing between pip verbose logs and PyPI JSON API to diagnose failed package deployments
Cig Nea
0 reputation · 24 Nov 2020, 20:54 UTC
125.3K views1
Loading…
0 reputation · 24 Nov 2020, 20:54 UTC
Determine whether pip's verbose installation output or the PyPI JSON API provides more reliable information for diagnosing why a package failed to deploy from PyPI.
Pip's verbose logs show each step of dependency resolution and HTTP interaction, but the level of detail varies between pip versions, and logs may not capture issues that occur before pip reaches the public index (e.g., mirror configuration or authentication problems).
The PyPI JSON API offers a complete view of released versions, yanked status, and dependencies as seen by a client with direct access to pypi.org, yet it cannot reveal problems caused by private indexes, proxies, or network restrictions that affect what pip actually sees.
Because the two sources complement each other, it is unclear which should be consulted first or whether both are needed depending on the nature of the failure (e.g., selection of a yanked version versus a timeout or authentication error).
35275 reputation · 25 Nov 2020, 01:44 UTC
Start with pip's verbose logs (pip install -vv). They show what your environment actually saw — the index URL, HTTP statuses, and why each candidate file was skipped. Reach for the PyPI JSON API second, to confirm what should exist on public PyPI. Neither alone covers both halves of the problem.
The log answers the question the API cannot: what did pip observe in this environment? With -vv you get the resolved index URL (revealing mirrors, proxies, or a forgotten --index-url), authentication failures, timeouts, and per-file skip reasons such as requires a different Python or no matching wheel tag. A 'No matching distribution found' error almost always decodes directly from these lines.
pypipython -m pip install -vv yourpackage==1.2.3 2>&1 | tee pip-debug.logThe API at https://pypi.org/pypi/<project>/<version>/json confirms ground truth about the release itself: whether the version exists, which files were uploaded, requires_python, and the yanked flag with its reason. Two cases where it beats the log:
Log wording varies across pip versions — don't parse exact strings in automation. A 200 from the JSON API doesn't prove files download correctly; CDN or hash-mismatch failures surface only in pip's output. And if your deployment uses a private index (devpi, Artifactory), the public API can actively mislead.
Failure happens during install → verbose log first. Failure is 'the release should exist but pip disagrees' → JSON API to verify the release, then the log to see why pip rejected it. If your log shows a non-pypi.org index URL, trust the log and treat the API as reference only.
Use comments to ask for clarification. Post a solution as an answer.
35,275 reputation · 24 Nov 2020, 23:42 UTC
To expand on the role of the JSON API in mirrored environments, it is useful to treat the API as a control group for debugging. When pip install -vv shows a "No matching distribution found" error despite the package existing on PyPI, the JSON API allows you to verify if the issue is upstream or local.
If the JSON API confirms the version and specific wheel tags (e.g., manylinux2014_x86_64) exist, but the pip logs show the client is only receiving a subset of files or a 404 from a local mirror, you have confirmed a mirror synchronization lag or a filtering policy. This distinction is critical because it moves the troubleshooting focus from the package's metadata to the infrastructure's caching layer.
To verify this, compare the urls array in the JSON API for a specific version against the HTTP requests captured in the -vv log. Any discrepancy in the file list or a mismatch in the digest values indicates the mirror is serving stale or corrupted data.