Document the cache directory (#6229)

crates/uv-cache/src/cli.rs

@@ -31,6 +31,7 @@ pub struct CacheArgs {
 
 impl Cache {
     /// Prefer, in order:
+    ///
     /// 1. A temporary cache directory, if the user requested `--no-cache`.
     /// 2. The specific cache directory specified by the user via `--cache-dir` or `UV_CACHE_DIR`.
     /// 3. The system-appropriate cache directory.

crates/uv-cli/src/lib.rs

@@ -405,6 +405,19 @@ pub enum CacheCommand {
     /// Prune all unreachable objects from the cache.
     Prune(PruneArgs),
     /// Show the cache directory.
+    ///
+    ///
+    /// By default, the cache is stored in  `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on Unix and
+    /// `{FOLDERID_LocalAppData}\uv\cache` on Windows.
+    ///
+    /// When `--no-cache` is used, the cache is stored in a temporary directory and discarded when
+    /// the process exits.
+    ///
+    /// An alternative cache directory may be specified via the `cache-dir` setting, the
+    /// `--cache-dir` option, or the `$UV_CACHE_DIR` environment variable.
+    ///
+    /// Note that it is important for performance for the cache directory to be located on the same
+    /// file system as the Python environment uv is operating on.
     Dir,
 }
 

docs/concepts/cache.md

@@ -83,3 +83,25 @@ pre-built wheels from the cache but retains any wheels that were built from sour
 running `uv cache prune --ci` at the end of your continuous integration job to ensure maximum cache
 efficiency. For an example, see the
 [GitHub integration guide](../guides/integration/github.md#caching).
+
+## Cache directory
+
+uv determines the cache directory according to, in order:
+
+1. A temporary cache directory, if `--no-cache` was requested.
+2. The specific cache directory specified via `--cache-dir`, `UV_CACHE_DIR`, or
+   [`tool.uv.cache-dir`](../reference/settings.md#cache-dir).
+3. A system-appropriate cache directory, e.g., `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on Unix and
+   `{FOLDERID_LocalAppData}\uv\cache` on Windows
+
+!!! note
+
+    uv _always_ requires a cache directory. When `--no-cache` is requested, uv will still use
+    a temporary cache for sharing data within that single invocation.
+
+    In most cases, `--refresh` should be used instead of `--no-cache` — as it will update the cache
+    for subsequent operations but not read from the cache.
+
+It is important for performance for the cache directory to be located on the same file system as the
+Python environment uv is operating on. Otherwise, uv will not be able to link files from the cache
+into the environment and will instead need to fallback to slow copy operations.

docs/reference/cli.md

@@ -5568,7 +5568,15 @@ uv cache prune [OPTIONS]
 
 ### uv cache dir
 
-Show the cache directory
+Show the cache directory.
+
+By default, the cache is stored in  `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on Unix and `{FOLDERID_LocalAppData}\uv\cache` on Windows.
+
+When `--no-cache` is used, the cache is stored in a temporary directory and discarded when the process exits.
+
+An alternative cache directory may be specified via the `cache-dir` setting, the `--cache-dir` option, or the `$UV_CACHE_DIR` environment variable.
+
+Note that it is important for performance for the cache directory to be located on the same file system as the Python environment uv is operating on.
 
 <h3 class="cli-reference">Usage</h3>