Using `uv tool` to Install and Run Python-Based Commands

Sometimes you do not want a library inside a project first. You want a command you can run. That difference is small in wording and huge in practice, which is why uv tool deserves its own mental shelf.

What `uv tool` is for

According to the notes, uv tool lets you run and install commands provided by Python packages.

That means the thing you care about is not mainly the package as code you import. The thing you care about is the executable command the package makes available.

That distinction helps avoid a very common beginner blur: installing a Python package into an environment is not the same task as installing a Python-based tool you want to call from the terminal.

Installing a tool

The notes describe uv tool install as the command that installs commands provided by a Python package.

uv tool install ruff

In a pattern like this, uv is still the actor, but the thing being touched is a command you want available for use. The package name you provide tells uv where that command comes from.

The important beginner idea is that you are installing for command access.

The inverse: uninstalling the tool

The notes make the inverse explicit: uninstall.

uv tool uninstall ruff

That makes this part of the toolset easier to reason about than project initialization. With tool install, the undo path is built into the command family itself.

Why `update-shell` matters

There is also a more structural subcommand in the notes: uv tool update-shell.

uv tool update-shell

Its job is to ensure that the tool executable directory is on your PATH.

This is one of those commands that makes sense only after you have felt the problem. You install a tool, but your shell still cannot find it. The package may be installed correctly, but the command is not visible in the places your shell checks for executables.

A tool can exist on your machine and still feel missing if your shell does not know where to look.

A practical sequence

A beginner-friendly pattern looks like this:

uv tool install ruff
uv tool update-shell

The first command installs the tool. The second makes sure the shell can find the executable directory if that is the missing link.

What this is not

uv tool install is not the same as uv pip install. The first is about commands provided by packages. The second is about package installation through a pip-compatible interface.

That difference is less about syntax than intent. Ask yourself what you want at the end: a command you can run, or a package installed into an environment.

What to remember

Use uv tool when the main thing you want is a Python-based command-line tool. Use install to add it, uninstall to remove it, and update-shell when the command exists but your shell is not finding it cleanly.

Raell Dottin's Technical Blog