expand on the storage documentation and add links back to it

Author: zsol

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
@@ -121,8 +125,9 @@ 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,7 +111,7 @@ $ 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,
+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.
 
@@ -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/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`:
 

docs/reference/storage.md

@@ -4,28 +4,30 @@ uv persists data in several locations on your system.
 
 ## Directory Strategies
 
-uv follows platform conventions for determining where to store different types of data.
+uv follows platform conventions (like
+[XDG](https://specifications.freedesktop.org/basedir-spec/latest/) on Unix) for determining where to
+store different types of data.
 
 Generally, it's best to configure these rather than each uv-specific storage location.
 
 ### Cache
 
-For temporary files and caches:
+Storage location for temporary files and caches:
 
-- `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on Unix systems
+- `$XDG_CACHE_HOME/uv` or `~/.cache/uv` on Unix systems
 - `%LOCALAPPDATA%\uv\cache` on Windows
 
 ### Data
 
-For persistent application data:
+Storage location for persistent application data:
 
 - `$XDG_DATA_HOME/uv` or `~/.local/share/uv` on Unix systems
 - `%APPDATA%\uv\data` on Windows
 - `.uv` in the working directory as a fallback
 
 ### Config
 
-For user configuration files:
+Storage location for user configuration files:
 
 - `$XDG_CONFIG_HOME/uv` or `~/.config/uv` on Unix systems
 - `%APPDATA%\uv` on Windows
@@ -35,26 +37,37 @@ For system configuration files:
 - `$XDG_CONFIG_DIRS/uv` or `/etc/uv` on Unix systems
 - `%PROGRAMDATA%\uv` on Windows
 
-### Binaries
+### Executables
 
-For executable files:
+Unlike other directory schemes above, uv follows the XDG standard on _all platforms_ by default,
+notably including Windows and macOS, as there is no clear alternative location to place executables
+on these platforms.
 
-- `$XDG_BIN_HOME`, `$XDG_DATA_HOME/../bin`, or `~/.local/bin` on all platforms
+The installation directory is determined by consulting the following environment variables if
+they're set:
+
+- `$XDG_BIN_HOME`
+- `$XDG_DATA_HOME/../bin`
+- `~/.local/bin`
+
+The above can be overridden by an environment variable specific to [tools](#tool-executables) or
+[Python executables](#python-executables).
+
+uv itself is also installed in the above folders by [the installer](./installer.md), and it can be
+overridden via the `UV_INSTALL_DIR` environment variable.
 
 ## Cache
 
-uv uses a local cache to avoid re-downloading and re-building dependencies. The cache contains
-wheels, source distributions, responses from package indexes, Git repositories, and Python
-interpreter metadata.
+uv uses a local cache to avoid re-downloading and re-building dependencies.
 
-By default, the cache is stored in the [cache home](#cache).
+By default, the cache is stored in the [cache home](#cache), which 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.
 
-Use the `--cache-dir` option or set the `UV_CACHE_DIR` environment variable to configure the cache
-location.
-
-For more details, see the [cache documentation](../concepts/cache.md).
+It is important for performance for the cache directory to be on the same filesystem as the
+[virtualenvs](#project-environments) uv operates on.
 
 ## Python versions
 
@@ -77,16 +90,15 @@ For more details, see the [Python versions documentation](../concepts/python-ver
 
 uv also supports adding Python executables to your `PATH`.
 
-By default, Python executables are stored in the [bin home](#bin).
+By default, Python executables are stored in the [bin home](#executables).
 
 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`. Each tool gets its own isolated
-environment.
+uv can install Python applications as tools using `uv tool install`.
 
 By default, tools are installed in the [data home](#data) under a `tools/` subdirectory, e.g.,
 `~/.local/share/uv/tools`
@@ -101,15 +113,16 @@ For more details, see the [tools documentation](../concepts/tools.md).
 
 When installing tools, uv will add tools to your `PATH`.
 
-By default, tool executbales are stored in the [bin home](#bin).
+By default, tool executables are stored in the [bin home](#executables).
 
 Use `uv tool dir --bin` to show the tool executable directory.
 
 Use the `UV_TOOL_BIN_DIR` environment variable to configure the executable directory.
 
 ## Configuration
 
-uv's behavior can be configured through configuration files stored in standard locations.
+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 [config directories](#config).
 

mkdocs.template.yml

@@ -237,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