Check uv tool updates before upgrading: latest versions and stored constraints

By ON Lab · Sources checked November 8, 2026

Use uv tool list --outdated to inspect available updates before changing installed tools. A reported latest version can be outside the requirement used at installation. Read that requirement with uv tool list --show-version-specifiers before choosing an upgrade. To deliberately replace the requirement, use a new uv tool install request.

This guide is for tools installed with uv tool install. It does not inventory every Python package on your computer. We checked uv 0.13.7 on macOS with a disposable tool directory, private executable directory, separate cache and a local package index. The package names and versions in the reproduction below are synthetic; no public package or personal tool installation was upgraded.

Take an inventory before running an upgrade

uv --version
uv tool list
uv tool list --show-version-specifiers
uv tool list --outdated

The ordinary list establishes which tools are installed. The requirement view helps distinguish an exact pin from a permitted range. The outdated view answers a different question: whether a newer release is available. Keep the outputs together rather than treating an update notice as permission to change a major version.

If --outdated is rejected, check uv tool list --help for your actual uv executable. Historical discussions requested this feature before it existed. Our current binary supports it; an old question is not evidence that your current installation lacks it. If the ordinary tool list is empty, use the temporary execution versus installed tools checklist before diagnosing an update problem.

Why “latest” and “upgrade” can give different answers

We published version 1.0 of a tiny test command to a local index and installed it with the requirement desk-update-demo<2. We then added versions 1.5 and 2.0 to that same index. Here is the recorded sequence; these commands are an explanation of our fixture, not package names to copy into a public-index installation.

The first outdated check left the installed version at 1.0, which we confirmed in the next inventory. The later upgrade was an explicit separate action. This is the practical value of checking first: you can review release notes, compatibility and your existing requirement before changing the command used by other scripts.

Choose the change you actually intend

To remain within the existing requirement, upgrade the package name listed in your inventory, then read the inventory again. Replace YOUR_TOOL_PACKAGE with that installed package name:

uv tool upgrade YOUR_TOOL_PACKAGE
uv tool list --show-version-specifiers

If your intention is to replace a range or pin, prepare a new installation request using the package's real name and a requirement you have reviewed. Quote expressions containing shell operators, for example uv tool install 'YOUR_TOOL_PACKAGE>=2'. The number 2 is only an example; it is not a safe target version for every tool. Record the current requirement and any extra dependencies or Python selection before recreating the installation.

A package name and its shell command can differ. Use the package identity for tool management and the exported command for its own version or smoke test. The package name versus executable guide explains how to identify the correct command without guessing.

Separate cache freshness from version policy

Our first inventory deliberately used uv tool list --outdated --no-cache after adding releases to the local index. This isolates “can the index show the release?” from “does the stored requirement permit it?” A fresh observation does not remove a version ceiling. Do not start by deleting every uv cache directory or manually editing the installed environment.

An offline result cannot establish that a release published since the last network observation does not exist. Likewise, an empty successful outdated result is scoped to the indexes and environment used for that check. A network, authentication or index error is a failed observation; preserve its error text rather than reporting that everything is current. Our reproduction used one local index and does not test your organization's private registry or credentials.

Verify the command after the change

Read the stored version and requirement again, then run the tool's own documented version command and one harmless operation relevant to your workflow. If the shell still launches another copy, inspect command resolution with your shell's normal lookup command before reinstalling again. Do not assume a successful package upgrade proves every script now calls that installation.

This check concerns installation policy and update visibility. It does not establish compatibility with your project's configuration, plugins, Python version or private package sources. If resolution fails, retain the complete conflicting requirements and inspect those constraints before widening them. Repeating the same conflicting upgrade request does not provide a new solution.

Sources

• docs.astral.sh: source guidance
• docs.astral.sh: source guidance
• github.com: source guidance