Skip to main content
Version: 1.0.0-beta.10

Cache

Dagger caches three types of data:

  1. Layers: This refers to build instructions and the results of some API calls.
  2. Volumes: This refers to the contents of a Dagger filesystem volume and is persisted across Dagger Engine sessions.
  3. Function calls: This refers to the values returned by calling a function in a module.

Cache inspection​

  • Show all the cache entry metadata:
dagger -m core api call engine local-cache entry-set entries
  • Show high level summaries of cache usage:
dagger -m core api call engine local-cache entry-set

Garbage collection​

The cache garbage collector runs in the background of the dagger engine, looking for unused layers and artifacts, and clears them up once they exceed the storage allowed by the cache policy.

The default cache policy attempts to keep the long-term cache storage under 75% of the total disk, while also ensuring that at least 20% of the disk remains free for other applications and tools.

The cache policy can be manually configured using the engine config.

Manual pruning​

To manually free up disk space used by the cache, use the following command:

dagger -m core api call engine local-cache prune

That will remove all cache entries not currently being used by connected clients from the disk.

To instead trigger a prune that follows the engine's configured cache garbage collection policy, use the following command:

dagger -m core api call engine local-cache prune --use-default-policy

This applies both the configured disk policies and the configured in-memory metadata limits. If garbage collection is disabled, there is no configured policy to follow. The command then prunes all releasable disk entries, exactly like a request with no options, and does not prune metadata.

To prune metadata on its own, pass the limits as absolute byte counts:

dagger -m core api call engine local-cache prune \
  --max-estimated-bytes=4294967296 \
  --target-estimated-bytes=3221225472

The example values are the built-in defaults. Metadata is pruned only when the estimate is above --max-estimated-bytes. Passing either flag prunes metadata, even when garbage collection is disabled. An omitted flag uses the engine's configured value. Values must be positive integers, and the target must be lower than the maximum. Percentages and size strings are not accepted.

A request with only these two flags does not prune the disk cache, though removing metadata can still free disk space. If a request also overrides the disk space limits, the disk prune runs first and the metadata prune second.

Full reset​

To start from a clean slate, remove the Dagger Engine container and Dagger's local cache and configuration directories.

Remove the Dagger Engine container (for Docker; adjust for other runtimes):

docker rm --force --volumes "$(docker ps --quiet --filter='name=^dagger-engine-')"

Then remove the dagger sub-directories of your local cache and configuration directories:

rm -rf ~/Library/Caches/dagger
rm -rf ~/Library/Application\ Support/dagger

These are the default paths ($XDG_CACHE_HOME and $XDG_CONFIG_HOME on Linux, or the platform equivalent) and may differ in your environment. Dagger resolves them with adrg/xdg (Go SDK and CLI), env-paths (Node.js), and platformdirs (Python).