Managing cache
This page describes how to manage the Earthly cache locally or on a remote runner, such as an Earthly Satellite.
Local cache
Local cache location
Earthly cache is persisted in a docker (or podman) volume called earthly-cache
on your system. When Earthly starts for the first time, it brings up a BuildKit daemon in a Docker container, which initializes the earthly-cache
volume. The volume is managed by Earthly's BuildKit daemon and there is a regular garbage-collection for old cache.
Specifying the local cache size limit
The default cache size is adaptable depending on available space on your system. It defaults to 10% or 10 GB, whichever is greater. If you would like to change the cache size, you can specify a different limit by modifying the cache_size_mb
and/or cache_size_pct
settings in the configuration. For example:
global:
cache_size_mb: 30000
cache_size_pct: 70
Resetting the local cache
To reset the cache, you can issue the command
earthly prune
You can also safely delete the cache manually, if the daemon is not running
docker stop earthly-buildkitd
docker rm earthly-buildkitd
docker volume rm earthly-cache
Earthly also has a command that automates the above:
earthly prune --reset
Cache on a remote runner / Earthly Satellite
Configuring the cache size on a remote runner
If you are using Earthly Satellites, you can simply launch a bigger satellite via the --size
flag: earthly sat launch --size ...
.
If you are using a self-hosted remote runner, you can configure the cache policy by passing the appropriate buildkit configuration to the buildkit container.
Resetting the cache on a remote runner
The command earthly prune
will work on remote runners too, albeit without the --reset
flag, which is not supported in a remote setting.
To cause a satellite to restart with a fresh cache, you can use the command earthly sat update --drop-cache
.
Auto-skip cache
The auto-skip cache is a cache that is used to skip large parts of a build in certain situations. It is used by the earthly --auto-skip
and BUILD --auto-skip
commands.
Unlike the layer cache and the cache mounts, the auto-skip cache is global and is stored in a cloud database.
To clear the entire auto-skip cache for your Earthly org, you can use the command earthly prune-auto-skip
.
To clear the auto-skip cache for an entire repository, you can use the command earthly prune-auto-skip --path github.com/foo/bar --deep
.
To clear the auto-skip cache for a specific target, you can use the command earthly prune-auto-skip --path github.com/foo/bar --target +my-target
.
Last updated
Was this helpful?