Enabling Docker Layer Caching
Premium Feature Notice: Docker Layer Caching
We now offer Docker Layer Caching on CircleCI 2.0 for an additional fee.
Note: This feature only works with whitelisted projects. To enable this feature, you must contact your Customer Success manager (email email@example.com and include a link to the project on CircleCI).
If your application is distributed as a Docker image, the image consists of layers that generally change more frequently toward the bottom of the
Dockerfile. This is because any lines that change in a Dockerfile invalidate the cache of that line and every line after it. The frequently changing layers are referred to as the top layers of the image after it is compiled.
Docker layer Caching in Remote Docker
Consider reusing the unchanged layers to significantly reduce image build times. By default, the Remote Docker Environment doesn’t provide layer caching, but you can enable this feature with a special option:
- setup_remote_docker: docker_layer_caching: true # default - true
docker_layer_caching is set to
true, CircleCI will try to reuse Docker Images (layers) from your previous builds. That is, every layer you built in a previous job will be accessible in the remote environment. However, in some cases your job may run in a clean environment, even if the configuration specifies
If you run many parallel jobs for the same project that depend on the same environment, all of them will be provided with a Remote Docker Environment. Docker Layer Caching guarantees jobs to have exclusive Remote Docker Environments that other jobs cannot access. However, some of the jobs may have cached layers, some may not have cached layers, and not all of the jobs will have identical cache.
docker_layer_caching option is not yet supported in an installable CircleCI release, but this functionality is available by using the
reusable: true option. Previously the
docker_layer_caching was called
reusable key is deprecated in favor of the
docker_layer_caching key. In addition, the
exclusive option is deprecated in favor of all VMs being treated as exclusive. This indicates that jobs are guaranteed to have an exclusive Remote Docker Environment that other jobs cannot access when using
Docker layer Caching in Machine Executor
Docker Layer Caching is also available for
machine executor, and it works in exactly the same way as described above. Enable Docker Layer Caching with the
machine executor by using the example below.
- machine: docker_layer_caching: true # default - false