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: trueMachine 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?
Go to Project Settings in CircleCI
Select Docker Layer Caching
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