From aad39febe582d510a891607ebe3803ada510131a Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Tue, 6 Aug 2024 15:21:18 -0500 Subject: [PATCH] Address some feedback in the tools documentation (#5827) --- docs/concepts/tools.md | 32 +++++++++++++++++++------------- docs/guides/tools.md | 12 +++++++----- 2 files changed, 26 insertions(+), 18 deletions(-) diff --git a/docs/concepts/tools.md b/docs/concepts/tools.md index bb57f13c6a4d..29372b95b64c 100644 --- a/docs/concepts/tools.md +++ b/docs/concepts/tools.md @@ -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 @@ -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 @@ -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 +$ uvx --with ``` +And installations: + ```console $ uv tool install --with ``` @@ -90,13 +95,13 @@ will fail and the command will error. ## Tool executables -Tool executables are all console entry points, script entry points, and binary scripts provided by a -Python package. Tool executables are symlinked into the `bin` directory on Unix and copied on +Tool executables include all console entry points, script entry points, and binary scripts provided +by a 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 @@ -114,13 +119,13 @@ The `bin` directory must be in the `PATH` variable for tool executables to be av shell. If it is not in the `PATH`, a warning will be displayed. The `uv tool update-shell` command can be used to add the `bin` directory to the `PATH` in common shell configuration files. -### Overriding executables +### Overwriting executables Installation of tools will not overwrite executables in the `bin` directory that were not previously 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 ` is nearly equivalent to: @@ -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 diff --git a/docs/guides/tools.md b/docs/guides/tools.md index 61dc5248d284..4ad0914a0fe1 100644 --- a/docs/guides/tools.md +++ b/docs/guides/tools.md @@ -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. @@ -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 @@ -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 @@ -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`: