Earthly 0.7
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.

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:
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

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.