-
Notifications
You must be signed in to change notification settings - Fork 605
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
125 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,124 @@ | ||
# Installing tools | ||
# Using tools | ||
|
||
Many Python packages provide command-line tools. uv has specialized support for invoking tools provided by these packages. | ||
|
||
## Using `uvx` | ||
|
||
The `uvx` command is an alias for `uv tool run` which can be used to invoke a tool without installing it. | ||
|
||
For example, to run `ruff`: | ||
|
||
```console | ||
$ uvx ruff | ||
``` | ||
|
||
Note this is exactly equivalent to: | ||
|
||
```console | ||
$ uv tool run ruff | ||
``` | ||
|
||
Arguments can be passed to the tools: | ||
|
||
```console | ||
$ uvx pycowsay hello from uv | ||
|
||
------------- | ||
< hello from uv > | ||
------------- | ||
\ ^__^ | ||
\ (oo)\_______ | ||
(__)\ )\/\ | ||
||----w | | ||
|| || | ||
|
||
``` | ||
|
||
## Commands with different package names | ||
|
||
In `uvx ruff`, the `ruff` package is installed to provide the `ruff` command. However, sometimes the package name differs from the command name. | ||
|
||
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 [email protected] check | ||
``` | ||
|
||
The `--from` option can also be used to specify package versions: | ||
|
||
To constrain to a range of versions: | ||
|
||
``` | ||
$ uvx --from 'ruff>0.2.0,<0.3.0' ruff check | ||
``` | ||
|
||
## 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 | ||
``` | ||
|
||
## Relationship to `uv run` | ||
|
||
The invocation `uv tool run ruff` is nearly equivalent to: | ||
|
||
```console | ||
$ uv run --isolated --with ruff -- ruff | ||
``` | ||
|
||
However, there are a couple notable differences when using uv's tool interface: | ||
|
||
- The `--with` is not needed — the required packge is inferred from the command name. | ||
- The temporary environment is cached in a dedicated location. | ||
- The `--isolated` flag is not needed — tools are always run isolated from the project. | ||
- If a tool is already installed, `uv tool run` will use the installed version but `uv run` will not. | ||
|
||
## Installing tools | ||
|
||
If a tool is used often, it can be useful to install it to a persistent environment instead of invoking `uvx` repeatedly. | ||
|
||
To install `ruff`: | ||
|
||
``` | ||
$ uv tool install ruff | ||
``` | ||
|
||
Unlike `uvx`, `uv tool install` operates on a _package_ and will install all executables provided by the tool. | ||
|
||
For example, the following will install `http`, `https`, and `httpie`: | ||
|
||
``` | ||
$ 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 | ||
``` |