Configuration reference

Global configuration values for earth can be stored on disk in the configuration file.

By default, earth reads the configuration file ~/.earthly/config.yaml; however, it can also be overridden with the --config command flag option.


The earthly config file is a yaml formatted file that looks like:

cache_path: <cache_path>
cache_size_mb: <cache_size_mb>
no_loop_device: true|false
buildkit_image: <buildkit_image>
url_instead_of: <url_instead_of>
auth: https|ssh
user: <username>
password: <password>


cache_size_mb: 20000
url_instead_of: ""
auth: https
user: alice
password: itsasecret

Global configuration reference


Specifies the location where build data is stored. The default location is /var/cache/earthly on Linux and ~/Library/Caches/earthly on macOS.


Specifies the total size of the buildkit cache, in MB. The buildkit daemon will allocate disk space for this size. Size less than 1000 (1GB) is not recommended. The default size if this option is not set is 10000 (10GB).

This setting is only used when the cache is initialized for the first time. In order to apply the setting immediately, issue the following command after changing the configuration

earth prune --reset


When set to true, disables the use of a loop device for storing the cache. By default, Earthly uses a file mounted as a loop device, so that it can control the type of filesystem used for the cache, in order to ensure that overlayfs can be mounted on top of it. If you are already using a filesystem compatible with overlayfs, then you can disable the loop device.

Git configuration reference

The git configuration is split up into global config options, or site-specific options.

global options

The global git options


Rewrites git URLs of a certain pattern. Similar to git-config url.<base>.insteadOf. Multiple values can be separated by commas. Format: <base>=<instead-of>[,...].

This setting allows rewriting all git URLs of the form https://example... into, or vice-versa.

For example:

  • --git-url-instead-of='' forces use of SSH-based URLs rather than HTTPS

  • --git-url-instead-of='' forces use of HTTPS-based local mirror for ssh-based repositories

NOTE: if the auth option is configured under a site-specific configuration, then the appropriate rewriting rule will be automatically applied.

site-specific options


The git repository hostname. For example, or


Either https or ssh (default). If https is specified, user and password fields are used to authenticate over https when pulling from git for the corresponding site.

See the Authentication guide for a guide on setting up authentication.


The https username to use when auth is set to https. This setting is ignored when auth is ssh.


The https password to use when auth is set to https. This setting is ignored when auth is ssh.