Overview

Docker Layer Caching (DLC) speeds up builds by reusing unchanged Docker image layers. This article answers common questions about DLC.

What is Docker Layer Caching?

DLC caches Docker image layers from your builds and reuses them in future builds. You only rebuild what changed, reducing build times.

How do I enable Docker Layer Caching?

Add docker_layer_caching: true to your configuration:

Remote Docker:

- setup_remote_docker:
    docker_layer_caching: true

Machine executor:

machine:
  docker_layer_caching: true

How much does it cost?

DLC costs 200 credits per job run.

Is DLC available on my plan?

Yes, DLC is available on all CircleCI plans.

How do I clear my cache?

1. Go to Project Settings in CircleCI
2. Select Docker Layer Caching
3. Click Delete Cache Contents

Why am I seeing cache misses?

When one step misses the cache, all later steps also miss. Common causes:

• Changes in your Dockerfile
• Changes in copied files (COPY or ADD commands)
• Different instruction order

How long does cached data last?

Cached layers expire after 3 days without use.

Can jobs in the same workflow share cache?

No. Cache uploads happen after jobs complete, so jobs in the same workflow typically cannot access each other's cache.

What is the storage limit?

The DLC storage limit is 15 GiB per organization. CircleCI automatically removes images when the limit is exceeded.

Does DLC speed up my executor images?

No. DLC only caches images you build with docker build or docker compose, not the container images specified in your executor.

What if I have frequent cache misses?

Consider using the CircleCI Docker orb for additional caching options.

Additional Notes

• DLC only works when you build Docker images in your jobs
• Dockerfile changes invalidate cache for all later layers
• Cache is shared across all projects in your organization

Additional Resources

• Docker Layer Caching Overview - Complete documentation
• How to Debug Docker Layer Cache Misses - Troubleshooting guide
• Troubleshooting DLC Teardown Errors - Resolving errors