mirror of
https://github.com/astral-sh/uv.git
synced 2025-11-01 20:31:12 +00:00
f971631adf
Basically sick of dealing with mixed formatting here. Going with the
number at
7c08e61b73/.editorconfig (L20)
155 lines
3.4 KiB
Markdown
155 lines
3.4 KiB
Markdown
# 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`:
|
|
|
|
```console
|
|
$ 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:
|
|
|
|
```console
|
|
$ 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`:
|
|
|
|
```console
|
|
$ uvx --from httpie http
|
|
```
|
|
|
|
## Requesting specific versions
|
|
|
|
To run a tool at a specific version, use `command@<version>`:
|
|
|
|
```console
|
|
$ uvx ruff@0.3.0 check
|
|
```
|
|
|
|
The `--from` option can also be used to specify package versions, as above:
|
|
|
|
```console
|
|
$ uvx --from 'ruff==0.3.0' ruff check
|
|
```
|
|
|
|
Or, to constrain to a range of versions:
|
|
|
|
```console
|
|
$ 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:
|
|
|
|
```console
|
|
$ 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`:
|
|
|
|
```console
|
|
$ 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`:
|
|
|
|
```console
|
|
$ 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:
|
|
|
|
```console
|
|
$ 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:
|
|
|
|
```console
|
|
$ 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:
|
|
|
|
```console
|
|
$ uv tool install httpie
|
|
```
|
|
|
|
Additionally, package versions can be included without `--from`:
|
|
|
|
```console
|
|
$ uv tool install 'httpie>0.1.0'
|
|
```
|
|
|
|
And, similarly, for package sources:
|
|
|
|
```console
|
|
$ uv tool install git+https://github.com/httpie/cli
|
|
```
|
|
|
|
As with `uvx`, installations can include additional packages:
|
|
|
|
```console
|
|
$ uv tool install mkdocs --with mkdocs-material
|
|
```
|
|
|
|
## Next steps
|
|
|
|
See the [tools concept](../concepts/tools.md) documentation for more details on how tools are
|
|
managed.
|