diff --git a/docs/concepts/cache.md b/docs/concepts/cache.md index 6610ccb55..1d5ba40a1 100644 --- a/docs/concepts/cache.md +++ b/docs/concepts/cache.md @@ -156,6 +156,13 @@ built from source. We recommend running `uv cache prune --ci` at the end of your integration job to ensure maximum cache efficiency. For an example, see the [GitHub integration guide](../guides/integration/github.md#caching). +## Sharing the cache + +uv shares a cache across processes on the same machine by default. + +See the [Docker integration guide](../guides/integration/docker.md) for details on how to share the +cache across containers. + ## Cache directory uv determines the cache directory according to, in order: diff --git a/docs/guides/integration/docker.md b/docs/guides/integration/docker.md index 55f86fad6..2a8649c93 100644 --- a/docs/guides/integration/docker.md +++ b/docs/guides/integration/docker.md @@ -328,6 +328,17 @@ ENV UV_COMPILE_BYTECODE=1 ### Caching +If you run containers with uv commands, your caching strategy might differ, depending on whether you +can reuse the cache between the builds and whether you are only using caching for building +containers, or also to run `uv` inside the containers. Also it depends on whether the host machine +that keeps your container engine is persistent or ephemeral (e.g., in CI). + +#### Reusing the uv cache for builds + +This makes sense when your container engine is persistent and you expect to run a number of builds +with the same container engine. This is not practically useful in CI systems, where the container +engine is usually ephemeral and when you run a single build of a container image. + A [cache mount](https://docs.docker.com/build/guide/mounts/#add-a-cache-mount) can be used to improve performance across builds: @@ -355,6 +366,31 @@ setting `UV_NO_CACHE`. ENV UV_CACHE_DIR=/opt/uv-cache/ ``` +#### Sharing the cache between running containers + +While using cache-mount is useful when you expect many builds to be run on the same host engine and +when the machine persistently stores the build cache, there is another case where container cache +might be shared between running containers, when you run uv commands inside running containers (for +example running `uv sync`). + +uv supports using the same cache between multiple processes by default and this also works between +different containers running on the same machine - either in parallel or when they are run +one-after-another sequentially by mounting the same uv cache directory in all the running +containers. + +To do it, you should mount the same folder from the machine to the `~/.cache/uv` directory in all +the running containers as read/write volumes. + +```bash +docker run --rm -it \ + --mount type=volume,source=/opt/uv-cache,target=/root/.cache/uv \ + ghcr.io/astral-sh/uv:debian uv sync +``` + +Again, this might not be practical in CI systems, where the container engine is ephemeral and you +run a single uv command in a single container, but is useful when you run multiple commands in +several containers - either in parallel or sequentially. + ### Intermediate layers If you're using uv to manage your project, you can improve build times by moving your transitive