From 35cdd43f881e37efac2f59f7c23fb970282948de Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Fri, 16 Aug 2024 17:01:11 -0400 Subject: [PATCH] Document dynamic metadata behavior for cache (#5993) ## Summary Closes https://github.com/astral-sh/uv/issues/5484. --- docs/concepts/cache.md | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/docs/concepts/cache.md b/docs/concepts/cache.md index b72a13e983c3..152a3e2d061b 100644 --- a/docs/concepts/cache.md +++ b/docs/concepts/cache.md @@ -17,6 +17,34 @@ The specifics of uv's caching semantics vary based on the nature of the dependen the local `.whl` or `.tar.gz` file). For directories, uv caches based on the last-modified time of the `pyproject.toml`, `setup.py`, or `setup.cfg` file. +If you're running into caching issues, uv includes a few escape hatches: + +- To force uv to revalidate cached data for all dependencies, pass `--refresh` to any command (e.g., + `uv sync --refresh` or `uv pip install --refresh ...`). +- To force uv to revalidate cached data for a specific dependency pass `--refresh-dependency` to any + command (e.g., `uv sync --refresh-package flask` or `uv pip install --refresh-package flask ...`). +- To force uv to ignore existing installed versions, pass `--reinstall` to any installation command + (e.g., `uv sync --reinstall` or `uv pip install --reinstall ...`). + +## Dynamic metadata + +Note that for local directory dependencies in particular (e.g., editables), uv will _only_ reinstall +the package if its `pyproject.toml`, `setup.py`, or `setup.cfg` file has changed. This is a +heuristic and, in some cases, may lead to fewer re-installs than desired. + +For example, if a local dependency uses `dynamic` metadata, you can instruct uv to _always_ +reinstall the package by adding `reinstall-package` to the `uv` section of your `pyproject.toml`: + +```toml title="pyproject.toml" +[tool.uv] +reinstall-package = ["my-package"] +``` + +This will force uv to rebuild and reinstall `my-package` on every run, regardless of whether the +package's `pyproject.toml`, `setup.py`, or `setup.cfg` file has changed. + +## Cache safety + It's safe to run multiple uv commands concurrently, even against the same virtual environment. uv's cache is designed to be thread-safe and append-only, and thus robust to multiple concurrent readers and writers. uv applies a file-based lock to the target virtual environment when installing, to @@ -25,13 +53,6 @@ avoid concurrent modifications across processes. Note that it's _not_ safe to modify the uv cache (e.g., `uv cache clean`) while other uv commands are running, and _never_ safe to modify the cache directly (e.g., by removing a file or directory). -If you're running into caching issues, uv includes a few escape hatches: - -- To force uv to revalidate cached data for all dependencies, run `uv pip install --refresh ...`. -- To force uv to revalidate cached data for a specific dependency, run, e.g., - `uv pip install --refresh-package flask ...`. -- To force uv to ignore existing installed versions, run `uv pip install --reinstall ...`. - ## Clearing the cache uv provides a few different mechanisms for removing entries from the cache: