Add a "storage" reference document

docs/concepts/configuration-files.md

@@ -42,13 +42,11 @@ 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.
-
-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_.
+uv will also discover user- and system-level configuration files, which must use the `uv.toml`
+format, according to [the storage documentation](../reference/storage.md#config); e.g., user-level
+configuration in `~/.config/uv/uv.toml`, and system-level configuration at `/etc/uv/uv.toml` on
+macOS and Linux. These cannot use the `pyproject.toml` format, which is intended to define a Python
+_project_.
 
 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

@@ -17,6 +17,10 @@ installations and all other Python installations as _system_ Python installation
     installed and managed by other tools. For example, if a Python installation is managed with
     `pyenv`, it would still be considered a _system_ Python version in uv.
 
+Managed Python versions are stored in a local directory, which can be configured using the
+`UV_PYTHON_INSTALL_DIR` environment variable. See the
+[storage documentation](../reference/storage.md#python-versions) for more information.
+
 ## Requesting a version
 
 A specific Python version can be requested with the `--python` flag in most uv commands. For
@@ -123,8 +127,10 @@ present, uv will install all the Python versions listed in the file.
 
 ### 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) on how to configure this
+directory.
 
 !!! tip
 

docs/concepts/tools.md

@@ -111,9 +111,9 @@ $ 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.
+By default, the uv tools directory is named `tools` and is in the uv
+[data directory](../reference/storage.md#data), 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:
 
@@ -264,16 +264,9 @@ Windows.
 
 ### The `bin` directory
 
-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:
-
-- `$UV_TOOL_BIN_DIR`
-- `$XDG_BIN_HOME`
-- `$XDG_DATA_HOME/../bin`
-- `$HOME/.local/bin`
+Executables are installed into the [user `bin` directory](../reference/storage.md#executables),
+e.g., `~/.local/bin`. This can be overridden by setting
+[the `UV_TOOL_BIN_DIR` environment variable](../reference/storage.md#tool-executables).
 
 Executables provided by dependencies of tool packages are not installed.
 

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

@@ -4,7 +4,8 @@
 
 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`.
+`XDG_DATA_HOME/../bin`. See [storage reference](./storage.md#Executables) for details on these
+locations and how to customize them.
 
 To change the installation path, use `UV_INSTALL_DIR`:
 
@@ -20,6 +21,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,116 @@
+# Storage
+
+uv persists data in several locations on your system.
+
+## Directory Strategies
+
+For determining where to store different types of data, uv follows the
+[XDG](https://specifications.freedesktop.org/basedir-spec/latest/) conventions on Linux and macOS
+and the platform defaults on Windows, with XDG paths where Windows does not have defaults.
+Generally, it's best to configure these rather than each uv-specific storage location.
+
+Here's a summary of the locations uv uses on each platform:
+
+| Purpose                    | Unix Default                                                                                                                                      | Windows Default                                                                                                                                 |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Temporary files and caches | `$XDG_CACHE_HOME/uv` or `~/.cache/uv` if `XDG_CACHE_HOME` is not set                                                                              | `%LOCALAPPDATA%\uv\cache`                                                                                                                       |
+| Persistent data            | `$XDG_DATA_HOME/uv`, or `~/.local/share/uv` if `XDG_DATA_HOME` is not set, or `.uv` in the current directory if the home directory is unavailable | `%APPDATA%\uv`, unless the legacy `%APPDATA%\uv\data` exists; if the home directory is unavailable, then `.uv` in the current directory is used |
+| User configuration files   | `$XDG_CONFIG_HOME/uv` or `~/.config/uv` if `XDG_CONFIG_HOME` is not set                                                                           | `%APPDATA%\uv`                                                                                                                                  |
+| System configuration files | `$XDG_CONFIG_DIRS/uv` or `/etc/uv` if `XDG_CONFIG_DIRS` is not set                                                                                | `%PROGRAMDATA%\uv`                                                                                                                              |
+| Executables                | `$XDG_BIN_HOME`, or `$XDG_DATA_HOME/../bin` if the former is not set, or `~/.local/bin` if `XDG_DATA_HOME` is also not set                        | same as on Unix                                                                                                                                 |
+| Environment                | `.venv` in the project or workspace directory                                                                                                     | same as on Unix                                                                                                                                 |
+
+## Caching
+
+uv uses a local cache to avoid re-downloading and re-building dependencies.
+
+By default, the cache is stored according to [the table above](#directory-strategies), and can be
+overridden via command line arguments, environment variables, or settings as detailed in
+[the cache documentation](../concepts/cache.md#cache-directory).
+
+Use `uv cache dir` to show the current cache directory path.
+
+It is important for performance for the cache directory to be on the same filesystem as the
+[virtual environments](#project-environments) uv operates on.
+
+## Python versions
+
+uv can download and manage Python versions.
+
+By default, Python versions are stored as persistent data according to
+[the table above](#directory-strategies), in a `python/` subdirectory, 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 configure 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).
+
+For more details on how uv manages Python versions, see the
+[dedicated documentation page](../concepts/python-versions.md).
+
+### Python executables
+
+uv also supports adding Python executables to your `PATH`.
+
+By default, Python executables are stored according to [the table above](#directory-strategies).
+
+Use `uv python dir --bin` to show the Python executable directory.
+
+Use the `UV_PYTHON_BIN_DIR` environment variable to configure the executable directory.
+
+## Tools
+
+uv can install Python applications as tools using `uv tool install`.
+
+By default, tools are installed as persistent data according to
+[the table above](#directory-strategies), under a `tools/` subdirectory, 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.
+
+For more details, see the [tools documentation](../concepts/tools.md).
+
+### Tool executables
+
+When installing tools, uv will add tools to your `PATH`.
+
+By default, tool executables are stored according to [the table above](#directory-strategies).
+
+Use `uv tool dir --bin` to show the tool executable directory.
+
+Use the `UV_TOOL_BIN_DIR` environment variable to configure the executable directory.
+
+## uv
+
+uv itself is also installed by [the installer](./installer.md) into the executables folder from
+[the table above](#directory-strategies), and this can be overridden via the `UV_INSTALL_DIR`
+environment variable.
+
+## Configuration
+
+uv's behavior (including most of the storage locations on this page) can be configured through
+configuration files stored in standard locations.
+
+Configuration files are located in the corresponding system- or user-specific locations from
+[the table above](#directory-strategies).
+
+For more details, see the [configuration files documentation](../concepts/configuration-files.md).
+
+## Project environments
+
+uv creates virtual environments for projects to isolate their dependencies.
+
+By default, project virtual environments are created in `.venv` within the project directory, and a
+workspace's environment is created with the same name in the workspace root.
+
+Use the `UV_PROJECT_ENVIRONMENT` environment variable to override this location, which is should be
+either an absolute path, or relative to the workspace root.
+
+For more details, see the
+[projects environment documentation](../concepts/projects/config.md#project-environment-path).

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