Enabling Docker Layer Caching
Docker, Machine, and iOS Builds > Enabling Docker Layer Caching
Premium Feature Notice: Docker Layer Caching
We now offer Docker Layer Caching on CircleCI 2.0 for an additional fee.
This document describes how to enable Docker Layer Caching (DLC) which is useful when you are building Docker images during your job or Workflow. DLC does not speed up downloading of Docker images used to run your jobs.
Note: A paid account is required to access this feature. If you are on a paid plan you can request access by opening a support ticket and including a link to your CircleCI project in the ticket.
Docker Layer Caching in Remote Docker
Consider enabling DLC to significantly reduce image build times by reusing the unchanged layers of the application image built during your job.
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.
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 - false
docker_layer_caching is set to
true, CircleCI will try to reuse Docker Images (layers) built during a previous job or workflow. 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 feature is not currently 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