pip-check-resolve

pip-check-resolve inspects an installed Python environment without changing it. It finds missing or incompatible dependencies and traces each problem back to the likely top-level packages that caused it.

Unlike a resolver, it answers why the environment that exists now is broken. It does not install packages, try alternative versions, or contact PyPI.

Usage

Run inside the environment to inspect the current interpreter:

$ pip-check-resolve

Or keep the tool isolated and point it at another environment:

$ uvx --from pip-check-resolve pip-check-resolve --python .venv/bin/python

Machine-readable output and expanded causal paths are available:

$ pip-check-resolve --python .venv/bin/python --format json
$ pip-check-resolve --all-paths --max-paths 100

Exit status is 0 for a consistent environment, 1 when package or metadata issues are found, and 2 when the target interpreter cannot be inspected.

What is checked

• missing dependencies;
• versions that do not satisfy their declared requirements;
• incompatible Requires-Python metadata;
• duplicate normalized distribution names;
• malformed package requirements or metadata.

Roots are identified from a distribution's REQUESTED marker when available and otherwise inferred from the installed dependency graph. Python packaging does not reliably preserve which extras were requested, so requirements conditional on extra are skipped and the report records that limitation.

Releasing

Releases are published from GitHub tags using PyPI Trusted Publishing. The tag must be the project version prefixed with v, for example v0.1.0. Update the version in both pyproject.toml and src/pip_check_resolve/__init__.py, commit, and then create and push the matching tag:

$ git tag v0.1.0
$ git push origin v0.1.0

The publish.yml workflow tests the package, builds and checks its wheel and source distribution, and publishes them to PyPI using short-lived OIDC credentials. The PyPI Trusted Publisher must use owner matplo, repository pip-check-resolve, workflow publish.yml, and environment pypi.