uv/docs/guides/tools.md

Using tools

Many Python packages provide applications that can be used as tools. uv has specialized support for easily invoking and installing tools.

Using uvx

The uvx command invokes a tool without installing it.

For example, to run ruff:

$ uvx ruff

!!! note

This is exactly equivalent to:

```console
$ uv tool run ruff
```

`uvx` is provided as a short alias since the operation is very common.

Arguments can be provided after the tool name:

$ uvx pycowsay hello from uv

  -------------
< hello from uv >
  -------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

Commands with different package names

When you invoke uvx ruff, uv installs the ruff package which provides the ruff command. However, sometimes the package and command names differ.

The --from option can be used to invoke a command from a specific package, e.g. http which is provided by httpie:

$ uvx --from httpie http

Requesting specific versions

To run a tool at a specific version, use command@<version>:

$ uvx ruff@0.3.0 check

The --from option can also be used to specify package versions, as above:

$ uvx --from 'ruff==0.3.0' ruff check

Or, to constrain to a range of versions:

$ uvx --from 'ruff>0.2.0,<0.3.0' ruff check

Note the @ syntax cannot be used for anything other than an exact version.

Requesting different sources

The --from option can also be used to install from alternative sources.

To pull from git:

$ uvx --from git+https://github.com/httpie/cli httpie

Commands with plugins

Additional dependencies can be included, e.g., to include mkdocs-material when running mkdocs:

$ uvx --with mkdocs-material mkdocs --help

Installing tools

If a tool is used often, it can be useful to install it to a persistent environment and add it to the PATH instead of invoking uvx repeatedly.

To install ruff:

$ uv tool install ruff

When a tool is installed, its executables are placed in a bin directory in the PATH which allows the tool to be run without uv. If it's not on the PATH, a warning will be displayed and uv tool update-shell can be used to add it to the PATH.

After installing ruff, it should be available:

$ ruff --version

Unlike uv pip install, installing a tool does not make its modules available in the current environment. For example, the following command will fail:

$ python -c "import ruff"

This isolation is important for reducing interactions and conflicts between dependencies of tools, scripts, and projects.

Unlike uvx, uv tool install operates on a package and will install all executables provided by the tool.

For example, the following will install the http, https, and httpie executables:

$ uv tool install httpie

Additionally, package versions can be included without --from:

$ uv tool install 'httpie>0.1.0'

And, similarly, for package sources:

$ uv tool install git+https://github.com/httpie/cli

As with uvx, installations can include additional packages:

$ uv tool install mkdocs --with mkdocs-material

Next steps

See the tools concept documentation for more details on how tools are managed.