Skip to content

Commit

Permalink
Address some feedback in the tools documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
zanieb committed Aug 6, 2024
1 parent f5b477a commit 9308017
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 15 deletions.
26 changes: 16 additions & 10 deletions docs/concepts/tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

Tools are Python packages that provide command-line interfaces. Tools can be invoked without
installation using `uvx`, in which case their dependencies are installed in a temporary virtual
environment isolated from the current project. Alternatively, tools can be installed with
`uv tool install`, in which case their executables are placed in the `PATH` — an isolated virtual
environment isolated from the current project. Tools can also be installed with `uv tool install`,
in which case their executables are [available on the `PATH`](#the-path) — an isolated virtual
environment is still used but it is not treated as disposable.

!!! note
Expand All @@ -13,9 +13,12 @@ environment is still used but it is not treated as disposable.

## Tool environments

Tools are installed into virtual environments which are created in the uv tools directory. When
running tools with `uvx` or `uv tool run`, the virtual environments are stored in the uv cache
directory and are treated as disposable.
When running a tool with `uvx` or `uv tool run`, a virtual environment is stored in the uv cache
directory and is treated as disposable. The environment is cached to reduce the overhead of
invocations.

When installing a tool with `uv tool install`, a virtual environment is created in the uv tools
directory.

### Tools directory

Expand Down Expand Up @@ -67,12 +70,14 @@ All tool environment mutations will reinstall the tool executables, even if they

### Including additional dependencies

Additional packages can be included during tool invocations and installations:
Additional packages can be included during tool invocations:

```console
$ uvx --with <extra-package> <tool-package>
$ uvx --with <extra-package> <tool>
```

And installations:

```console
$ uv tool install --with <extra-package> <tool-package>
```
Expand All @@ -94,9 +99,9 @@ Tool executables are all console entry points, script entry points, and binary s
Python package. Tool executables are symlinked into the `bin` directory on Unix and copied on
Windows.

### `bin` directory
### The `bin` directory

Executables are installed into the user's `bin` directory following the XDG standard, e.g.,
Executables are installed into the user `bin` directory following the XDG standard, e.g.,
`~/.local/bin`. Unlike other directory schemes in uv, the XDG standard is used on _all platforms_
notably including Windows and macOS — there is no clear alternative location to place executables on
these platforms. The installation directory is determined from the first available environment
Expand All @@ -120,7 +125,7 @@ Installation of tools will not overwrite executables in the `bin` directory that
installed by uv. For example, if `pipx` has been used to install a tool, `uv tool install` will
fail. The `--force` flag can be used to override this behavior.

## `uv tool run` vs `uv run`
## Relationship to `uv run`

The invocation `uv tool run <name>` is nearly equivalent to:

Expand All @@ -135,3 +140,4 @@ However, there are a couple notable differences when using uv's tool interface:
- The `--no-project` 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.
- The project will be built and installed instead of using an editable installation
12 changes: 7 additions & 5 deletions docs/guides/tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Many Python packages provide applications that can be used as tools. uv has specialized support for
easily invoking and installing tools.

## Using `uvx`
## Running tools

The `uvx` command invokes a tool without installing it.

Expand Down Expand Up @@ -39,9 +39,11 @@ $ uvx pycowsay hello from uv

```

Tools are installed into temporary, isolated environmnets when using `uvx`.

## Commands with different package names

When you invoke `uvx ruff`, uv installs the `ruff` package which provides the `ruff` command.
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
Expand Down Expand Up @@ -77,7 +79,7 @@ Note the `@` syntax cannot be used for anything other than an exact version.

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

To pull from git:
For example, to pull from git:

```console
$ uvx --from git+https://github.com/httpie/cli httpie
Expand All @@ -93,8 +95,8 @@ $ 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.
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.

To install `ruff`:

Expand Down

0 comments on commit 9308017

Please sign in to comment.