Add a "storage" reference document (#15954)

Co-authored-by: Zanie Blue <contact@zanie.dev>

docs/concepts/configuration-files.md

@@ -42,13 +42,14 @@ default = true
     `pyproject.toml` files are present in a directory, configuration will be read from `uv.toml`, and
     `[tool.uv]` section in the accompanying `pyproject.toml` will be ignored.
 
-uv will also discover user-level configuration at `~/.config/uv/uv.toml` (or
-`$XDG_CONFIG_HOME/uv/uv.toml`) on macOS and Linux, or `%APPDATA%\uv\uv.toml` on Windows; and
-system-level configuration at `/etc/uv/uv.toml` (or `$XDG_CONFIG_DIRS/uv/uv.toml`) on macOS and
-Linux, or `%SYSTEMDRIVE%\ProgramData\uv\uv.toml` on Windows.
+uv will also discover `uv.toml` configuration files in the user- and system-level
+[configuration directories](../reference/storage.md#configuration-directories), e.g., user-level
+configuration in `~/.config/uv/uv.toml`, and system-level configuration at `/etc/uv/uv.toml` on
+macOS and Linux.
 
-User-and system-level configuration must use the `uv.toml` format, rather than the `pyproject.toml`
-format, as a `pyproject.toml` is intended to define a Python _project_.
+!!! important
+
+    User- and system-level configuration files cannot use the `pyproject.toml` format.
 
 If project-, user-, and system-level configuration files are found, the settings will be merged,
 with project-level configuration taking precedence over the user-level configuration, and user-level

docs/concepts/python-versions.md

@@ -121,10 +121,15 @@ present, uv will install all the Python versions listed in the file.
     The available Python versions are frozen for each uv release. To install new Python versions,
     you may need upgrade uv.
 
+See the [storage documentation](../reference/storage.md#python-versions) for details about where
+installed Python versions are stored.
+
 ### Installing Python executables
 
-uv installs Python executables into your `PATH` by default, e.g., `uv python install 3.12` will
-install a Python executable into `~/.local/bin`, e.g., as `python3.12`.
+uv installs Python executables into your `PATH` by default, e.g., on Unix `uv python install 3.12`
+will install a Python executable into `~/.local/bin`, e.g., as `python3.12`. See the
+[storage documentation](../reference/storage.md#python-executables) for more details about the
+target directory.
 
 !!! tip
 

docs/concepts/tools.md

@@ -35,9 +35,14 @@ treated as disposable, i.e., if you run `uv cache clean` the environment will be
 environment is only cached to reduce the overhead of repeated invocations. If the environment is
 removed, a new one will be created automatically.
 
-When installing a tool with `uv tool install`, a virtual environment is created in the uv tools
-directory. The environment will not be removed unless the tool is uninstalled. If the environment is
-manually deleted, the tool will fail to run.
+When installing a tool with `uv tool install`, a virtual environment is created in the
+[uv tools directory](../reference/storage.md#tools). The environment will not be removed unless the
+tool is uninstalled. If the environment is manually deleted, the tool will fail to run.
+
+!!! important
+
+    Tool environments are _not_ intended to be mutated directly. It is strongly recommended never to
+    mutate a tool environment manually, e.g., with a `pip` operation.
 
 ## Tool versions
 
@@ -109,26 +114,6 @@ $ uv tool install ruff@latest
 $ uv tool install ruff@0.6.0
 ```
 
-## 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>`.
-
-!!! important
-
-    Tool environments are _not_ intended to be mutated directly. It is strongly recommended never to
-    mutate a tool environment manually, e.g., with a `pip` operation.
-
 ## Upgrading tools
 
 Tool environments may be upgraded via `uv tool upgrade`, or re-created entirely via subsequent
@@ -259,35 +244,23 @@ tool may be unusable.
 ## Tool executables
 
 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.
+by a Python package. Tool executables are symlinked into the
+[executable directory](../reference/storage.md#tool-executables) on Unix and copied on Windows.
 
-### The `bin` directory
+!!! note
 
-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
-variable:
+    Executables provided by dependencies of tool packages are not installed.
 
-- `$UV_TOOL_BIN_DIR`
-- `$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.
+The [executable directory](../reference/storage.md#executable-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 executable directory to
+the `PATH` in common shell configuration files.
 
 ### 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.
+Installation of tools will not overwrite executables in the executable 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.
 
 ## Relationship to `uv run`
 

docs/getting-started/installation.md

@@ -260,7 +260,8 @@ If you need to remove uv from your system, follow these steps:
 
     !!! tip
 
-        Before removing the binaries, you may want to remove any data that uv has stored.
+        Before removing the binaries, you may want to remove any data that uv has stored. See the
+        [storage reference](../reference/storage.md) for details on where uv stores data.
 
 2.  Remove the uv, uvx, and uvw binaries:
 

docs/reference/index.md

@@ -5,6 +5,7 @@ The reference section provides information about specific parts of uv:
 - [Commands](./cli.md): A reference for uv's command line interface.
 - [Settings](./settings.md): A reference for uv's configuration schema.
 - [Resolver](./internals/resolver.md): Details about the internals of uv's resolver.
+- [Storage](./storage.md): Information about where uv stores data on your system.
 - [Policies](./policies/index.md): uv's versioning policy, platform support policy, and license.
 
 Looking for a broader overview? Check out the [concepts](../concepts/index.md) documentation.

docs/reference/installer.md

@@ -2,9 +2,7 @@
 
 ## Changing the installation path
 
-By default, uv is installed to `~/.local/bin`. If `XDG_BIN_HOME` is set, it will be used instead.
-Similarly, if `XDG_DATA_HOME` is set, the target directory will be inferred as
-`XDG_DATA_HOME/../bin`.
+By default, uv is installed in the user [executable directory](./storage.md#executable-directory).
 
 To change the installation path, use `UV_INSTALL_DIR`:
 
@@ -20,6 +18,12 @@ To change the installation path, use `UV_INSTALL_DIR`:
     PS> powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "C:\Custom\Path";irm https://astral.sh/uv/install.ps1 | iex}
     ```
 
+!!! note
+
+    Changing the installation path only affects where the uv binary is installed. uv will still store
+    its data (cache, Python installations, tools, etc.) in the default locations. See the
+    [storage reference](./storage.md) for details on these locations and how to customize them.
+
 ## Disabling shell modifications
 
 The installer may also update your shell profiles to ensure the uv binary is on your `PATH`. To

docs/reference/storage.md

@@ -0,0 +1,200 @@
+# Storage
+
+## Storage directories
+
+uv uses the following high-level directories for storage.
+
+For each location, uv checks for the existence of environment variables in the given order and uses
+the first path found.
+
+The paths of storage directories are platform-specific. uv follows the
+[XDG](https://specifications.freedesktop.org/basedir-spec/latest/) conventions on Linux and macOS
+and the [Known Folder](https://learn.microsoft.com/en-us/windows/win32/shell/known-folders) scheme
+on Windows.
+
+### Temporary directory
+
+The temporary directory is used for ephemeral data.
+
+=== "Unix"
+
+    1. `$TMPDIR`
+    1. `/tmp`
+
+=== "Windows"
+
+    1. `%TMP%`
+    1. `%TEMP%`
+    1. `%USERPROFILE%`
+
+### Cache directory
+
+The cache directory is used for data that is disposable, but is useful to be long-lived.
+
+=== "Unix"
+
+    1. `$XDG_CACHE_HOME/uv`
+    1. `$HOME/.cache/uv`
+
+=== "Windows"
+
+    1. `%LOCALAPPDATA%\uv\cache`
+    1. `uv\cache` within [`FOLDERID_LocalAppData`](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid#FOLDERID_LocalAppData)
+
+### Persistent data directory
+
+The persistent data directory is used for non-disposable data.
+
+=== "Unix"
+
+    1. `$XDG_DATA_HOME/uv`
+    1. `$HOME/.local/share/uv`
+    1. `$CWD/.uv`
+
+=== "Windows"
+
+    1. `%APPDATA%\uv\data`
+    1. `.\.uv`
+
+### Configuration directories
+
+The configuration directories are used to store changes to uv's settings.
+
+User-level configuration
+
+=== "Unix"
+
+    1. `$XDG_CONFIG_HOME/uv`
+    1. `$HOME/.config/uv`
+
+=== "Windows"
+
+    1. `%APPDATA%\uv`
+    1. `uv` within [`FOLDERID_RoamingAppData`](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid#FOLDERID_RoamingAppData)
+
+System-level configuration
+
+=== "Unix"
+
+    1. `$XDG_CONFIG_DIRS/uv`
+    1. `/etc/uv`
+
+=== "Windows"
+
+    1. `%PROGRAMDATA%\uv`
+    1. `uv` within [`FOLDERID_AppDataProgramData`](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid#FOLDERID_AppDataProgramData)
+
+### Executable directory
+
+The executable directory is used to store files that can be run by the user, i.e., a directory that
+should be on the `PATH`.
+
+=== "Unix"
+
+    1. `$XDG_BIN_HOME`
+    1. `$XDG_DATA_HOME/../bin`
+    1. `$HOME/.local/bin`
+
+=== "Windows"
+
+    1. `%XDG_BIN_HOME%`
+    1. `%XDG_DATA_HOME%\..\bin`
+    1. `%USERPROFILE%\.local\bin`
+
+## Types of data
+
+### Dependency cache
+
+uv uses a local cache to avoid re-downloading and re-building dependencies.
+
+By default, the cache is stored in the [cache directory](#cache-directory) but it can be overridden
+via command line arguments, environment variables, or settings as detailed in
+[the cache documentation](../concepts/cache.md#cache-directory). When the cache is disabled, the
+cache will be stored in a [temporary directory](#temporary-directory).
+
+Use `uv cache dir` to show the current cache directory path.
+
+!!! important
+
+    For optimal performance, the cache directory needs to be on the same filesystem as virtual
+    environments.
+
+### Python versions
+
+uv can install managed [Python versions](../concepts/python-versions.md), e.g., with
+`uv python install`.
+
+By default, Python versions managed by uv are stored in a `python/` subdirectory of the
+[persistent data directory](#persistent-data-directory), e.g., `~/.local/share/uv/python`.
+
+Use `uv python dir` to show the Python installation directory.
+
+Use the `UV_PYTHON_INSTALL_DIR` environment variable to override the installation directory.
+
+!!! note
+
+    Changing where Python is installed will not be automatically reflected in existing virtual environments; they will keep referring to the old location, and will need to be updated manually (e.g. by re-creating them).
+
+### Python executables
+
+uv installs executables for [Python versions](#python-versions), e.g., `python3.13`.
+
+By default, Python executables are stored in the [executable directory](#executable-directory).
+
+Use `uv python dir --bin` to show the Python executable directory.
+
+Use the `UV_PYTHON_BIN_DIR` environment variable to override the Python executable directory.
+
+### Tools
+
+uv can install Python packages as [command-line tools](../concepts/tools.md) using
+`uv tool install`.
+
+By default, tools are installed in a `tools/` subdirectory of the
+[persistent data directory](#persistent-data-directory), e.g., `~/.local/share/uv/tools`.
+
+Use `uv tool dir` to show the tool installation directory.
+
+Use the `UV_TOOL_DIR` environment variable to configure the installation directory.
+
+### Tool executables
+
+uv installs executables for installed [tools](#tools), e.g., `ruff`.
+
+By default, tool executables are stored in the [executable directory](#executable-directory).
+
+Use `uv tool dir --bin` to show the tool executable directory.
+
+Use the `UV_TOOL_BIN_DIR` environment variable to configure the tool executable directory.
+
+### The uv executable
+
+When using uv's [standalone installer](./installer.md) to install uv, the `uv` and `uvx` executables
+are installed into the [executable directory](#executable-directory).
+
+Use the `UV_INSTALL_DIR` environment variable to configure uv's installation directory.
+
+### Configuration files
+
+uv's behavior can be configured through TOML files.
+
+Configuration files are discovered in the [configuration directories](#configuration-directories).
+
+For more details, see the [configuration files documentation](../concepts/configuration-files.md).
+
+### Project virtual environments
+
+When working on [projects](../concepts/projects/index.md), uv creates a dedicated virtual
+environment for each project.
+
+By default, project virtual environments are created in `.venv` in the project or workspace root,
+i.e., next to the `pyproject.toml`.
+
+Use the `UV_PROJECT_ENVIRONMENT` environment variable to override this location. For more details,
+see the
+[projects environment documentation](../concepts/projects/config.md#project-environment-path).
+
+### Script virtual environments
+
+When running [scripts with inline metadata](../guides/scripts.md), uv creates a dedicated virtual
+environment for each script in the [cache directory](#cache-directory).

mkdocs.template.yml

@@ -144,6 +144,7 @@ plugins:
         Reference:
           - reference/cli.md
           - reference/settings.md
+          - reference/storage.md
           - reference/environment.md
           - reference/installer.md
 extra_css:
@@ -236,6 +237,7 @@ nav:
       - Commands: reference/cli.md
       - Settings: reference/settings.md
       - Environment variables: reference/environment.md
+      - Storage: reference/storage.md
       - Installer options: reference/installer.md
       - Troubleshooting:
           - reference/troubleshooting/index.md