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.yml; 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_size_mb: <cache_size_mb>
no_loop_device: false|true
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 total size of the BuildKit cache, in MB. The BuildKit daemon uses this setting to configure automatic garbage collection of old cache. A value of 0 causes the size to be adaptive depending on how much space is available on your system. The default is 0.

no_loop_device (deprecated)

When set to true, disables the use of a loop device for storing the cache. This setting is now set to true by default and will be removed in a future version of Earthly.

cache_path (obsolete)

This option is obsolete and it is ignored. Earthly cache has moved to a Docker volume. For more information see the page on managing cache.

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.