Using tools
Many Python packages provide applications that can be used as tools. uv has specialized support for easily invoking and installing tools.
Running tools
The uvx command invokes a tool without installing it.
For example, to run ruff:
Arguments can be provided after the tool name:
$ uvx pycowsay hello from uv
-------------
< hello from uv >
-------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
Tools are installed into temporary, isolated environments when using uvx.
Note
If you are running a tool in a project and the tool requires that
your project is installed, e.g., when using pytest or mypy, you'll want to use
uv run instead of uvx. Otherwise, the tool will be run in
a virtual environment that is isolated from your project.
If your project has a flat structure, e.g., instead of using a src directory for modules,
the project itself does not need to be installed and uvx is fine. In this case, using
uv run is only beneficial if you want to pin the version of the tool in the project's
dependencies.
Commands with different package names
When uvx ruff is invoked, 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:
Requesting specific versions
To run a tool at a specific version, use command@<version>:
$ uvx [email protected] check
To run a tool at the latest version, use command@latest:
The --from option can also be used to specify package versions, as above:
Or, to constrain to a range of versions:
Note the @ syntax cannot be used for anything other than an exact version.
Requesting extras
The --from option can be used to run a tool with extras:
This can also be combined with version selection:
Requesting different sources
The --from option can also be used to install from alternative sources.
For example, to pull from git:
You can also pull the latest commit from a specific named branch:
Or pull a specific tag:
$ uvx --from git+https://github.com/httpie/[email protected] httpie
Or even a specific commit:
Commands with plugins
Additional dependencies can be included, e.g., to include mkdocs-material when running mkdocs:
Installing tools
If a tool is used often, it is useful to install it to a persistent environment and add it to the
PATH instead of invoking uvx repeatedly.
Tip
uvx is a convenient alias for uv tool run. All of the other commands for interacting with
tools require the full uv tool prefix.
To 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:
Unlike uv pip install, installing a tool does not make its modules available in the current
environment. For example, the following command will fail:
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:
Additionally, package versions can be included without --from:
And, similarly, for package sources:
As with uvx, installations can include additional packages:
Upgrading tools
To upgrade a tool, use uv tool upgrade:
Tool upgrades will respect the version constraints provided when installing the tool. For example,
uv tool install ruff >=0.3,<0.4 followed by uv tool upgrade ruff will upgrade Ruff to the latest
version in the range >=0.3,<0.4.
To instead replace the version constraints, re-install the tool with uv tool install:
To instead upgrade all tools:
Next steps
To learn more about managing tools with uv, see the Tools concept page and the command reference.
Or, read on to learn how to to work on projects.