Write tools concept doc (#5207)

docs/first-steps.md

@@ -41,7 +41,7 @@ These commands are used to manage command-line tools written in Python.
 
 - `uv tool run`
 
-See the documentation on [tools](./preview/tools.md) for more details on getting started.
+See the documentation on [tools](./tools.md) for more details on getting started.
 
 ### Low-level plumbing commands
 

docs/guides/tools.md

@@ -84,21 +84,6 @@ Additional dependencies can be included, e.g., to include `mkdocs-material` when
 $ 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` option is not needed — the required package 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.
@@ -109,7 +94,7 @@ To install `ruff`:
 $ 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`, we'll warn you).
+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:
 
@@ -139,8 +124,18 @@ Additionally, package versions can be included without `--from`:
 $ uv tool install 'httpie>0.1.0'
 ```
 
-And similarly for package sources:
+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](../tools.md) documentation for more details on how tools are managed.

docs/preview/tools.md

@@ -1,7 +0,0 @@
-**Warning: This documentation refers to experimental features that may change.**
-
-# Command-line tools
-
-## Running a tool
-
-## Installing a tool

docs/tools.md

@@ -0,0 +1,114 @@
+# Tools
+
+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 is still used but it is not treated as disposable.
+
+!!! note
+
+    See the [tools guide](./guides/tools.md) for an introduction to working with the tools interface — this document discusses details of tool management.
+
+## 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.
+
+### Tools directory
+
+By default, the uv tools directory is named `tools` and is in the uv application state directory, e.g., `~/.local/share/uv/tools`. The location may be customized with the `UV_TOOL_DIR` environment variable.
+
+To display the path to the tool installation directory:
+
+```console
+$ uv tool dir
+```
+
+Tool environments are placed in a directory with the same name as the tool package, e.g., `.../tools/<name>`.
+
+### Mutating tool environments
+
+Tool environments are _not_ intended to be mutated directly. It is strongly recommended never to mutate a tool environment manually with a `pip` operation.
+
+Tool environments may be either mutated or re-created by subsequent `uv tool install` operations.
+
+To upgrade a single package in a tool environment:
+
+```
+$ uv tool install black --upgrade-package click
+```
+
+To upgrade all packages in a tool environment
+
+```
+$ uv tool install black --upgrade
+```
+
+To reinstall a single package in a tool environment:
+
+```
+$ uv tool install black --reinstall-package click
+```
+
+To reinstall all packages in a tool environment
+
+```
+$ uv tool install black --reinstall
+```
+
+All tool environment mutations will reinstall the tool executables, even if they have not changed.
+
+### Including additional dependencies
+
+Additional packages can be included during tool invocations and installations:
+
+```console
+$ uvx --with <extra-package> <tool-package>
+```
+
+```console
+$ uv tool install --with <extra-package> <tool-package>
+```
+
+The `--with` option can be provided multiple times to include additional packages.
+
+The `--with` option supports package specifications, so a specific version can be requested:
+
+```console
+$ uvx --with <extra-package>==<version> <tool-package>
+```
+
+If the requested version conflicts with the requirements of the tool package, package resolution 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 Windows.
+
+### `bin` directory
+
+Executables are installed into the user's `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 variable:
+
+- `$XDG_BIN_HOME`
+- `$XDG_DATA_HOME/../bin`
+- `$HOME/.local/bin`
+
+Executables provided by dependencies of tool packages are not installed.
+
+### The `PATH`
+
+The `bin` directory must be in the `PATH` variable for tool executables to be available from the 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
+
+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`
+
+The invocation `uv tool run <name>` is nearly equivalent to:
+
+```console
+$ uv run --isolated --with <name> -- <name>
+```
+
+However, there are a couple notable differences when using uv's tool interface:
+
+- The `--with` option is not needed — the required package 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.

mkdocs.template.yml

@@ -78,7 +78,7 @@ nav:
       - Working on projects: guides/projects.md
   - Concepts:
       - Projects: projects.md
-      - Command-line tools: preview/tools.md
+      - Tools: tools.md
       - Python versions: python-versions.md
       - Workspaces: preview/workspaces.md
       - Dependency sources: preview/dependencies.md