konsti
db371560bc
To enforce the 100 character line limit in markdown files introduced in https://github.com/astral-sh/uv/pull/5635, and to automate the formatting of markdown files, i've added prettier and formatted our markdown files with it. I've excluded the changelog and the generated references documentation from this for having too many changes, but we can also include them. I'm not particular on which style we use. My main motivations are (major) not having to reflow markdown files myself anymore and (minor) consistence between all markdown files. I've chosen prettier for similar reason as we chose black, it's a single good style that's automated and shared in the community. I do prefer prettier's style of not breaking inside of a link name though. This PR is in two parts, the first adds prettier to CI and documents using it, while the second actually formats the docs. When merge conflicts arise, we can drop the last commit and regenerate it with `npx prettier --prose-wrap always --write BENCHMARKS.md CONTRIBUTING.md README.md STYLE.md docs/*.md docs/concepts/**/*.md docs/guides/**/*.md docs/pip/**/*.md`. --------- Co-authored-by: Zanie Blue <contact@zanie.dev>
156 lines
3.4 KiB
Markdown
156 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.
|