Comment on page
Managing cache
This page describes how to manage the Earthly cache locally or on a remote runner, such as an Earthly Satellite.
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.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
Checking current size of the cache volume
You can check the current size of the cache volume by running:
sudo du -h /var/lib/docker/volumes/earthly-cache | tail -n 1
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
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.
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.Last modified 29d ago