uv-readiness

Find out whether a uv project can move to a new Python version, and what is in the way.

uvx uv-readiness 3.14

Run it in a directory that has a uv.lock. It checks every locked package, direct or transitive, and never modifies your project.

What it tells you

• What blocks the upgrade. Packages that ship compiled wheels but none for the target Python, drawn as a tree from your project down, so you can see which dependency pulls each one in.
• What fixes it. It re-locks a temporary copy of the project for the target Python and prints the uv lock command that works. When no upgrade helps, it shows uv's own explanation of which requirement holds things back.
• What "ready" rests on. Most packages ship py3-none wheels that install on any Python 3, which says nothing about one particular version. The summary counts those apart from packages with a wheel built for the target, and a classifier check lists the ones that do not declare the target yet.

Two signals, used differently

The tool reads both wheels and classifiers. Which one applies depends on the package.

So for most of your packages the classifier is the only version-specific information there is, and the report shows it. It does not fail a run, because a missing classifier usually means the author has not updated the metadata, not that the package is broken.

This is the uv counterpart to pdm-readiness, which reads classifiers for direct dependencies only.

Usage

uv-readiness <python> [--project DIR] [--offline] [--json] [--verbose]

uv has no plugin system, so this is a standalone command, not uv readiness. It needs uv on your PATH whenever it has to ask the resolver.

In CI

- uses: actions/checkout@v7
- uses: astral-sh/setup-uv@v10.2.0
- run: uvx uv-readiness 3.14

The step fails until the project is ready. See Running in CI for a scheduled workflow and for using the JSON output.

Documentation

• How it works: what is read, what is run, and where.
• Reading the report: every section, status and note.
• JSON output: the fields behind --json.
• Running in CI: workflows and exit codes.
• Limits: what the tool cannot tell you.

Limits worth knowing first

• A wheel shows that a package installs, not that it was tested. A py3-none wheel counts as ready even if the code uses something the target Python removed.
• Platform tags are ignored: a wheel for the target Python on any platform counts.
• The suggested command is resolved for the target Python only. In a project that spans several Python versions, uv may pick other versions for the older ones.

The full list is in Limits.

Development

uv sync
uv run pytest                 # unit tests
uv run pytest -m network      # runs real `uv lock` and queries PyPI
uv run ruff check && uv run ruff format --check && uv run ty check
vhs docs/demo.tape            # re-record the demo GIF

License

MIT. See LICENSE.