How do I enable Docker Layer Caching in CircleCI, and how is it billed/charged?

Docker-heavy teams usually hit the same wall: builds get slower as images grow, and every change feels like a full rebuild. Docker Layer Caching (DLC) in CircleCI is how you keep AI-speed iteration without paying the “cold build” tax on every pipeline run—and you only pay for it when a job actually uses the cache.

Quick Answer: Docker Layer Caching in CircleCI reuses previously built Docker image layers between job runs so your docker build steps run much faster. It is billed per job run that uses DLC: 200 credits per job run (about $0.12 per job), in addition to your normal compute credits.

The Quick Overview

What It Is: A CircleCI feature that persists and reuses Docker image layers between jobs in a pipeline so subsequent builds only rebuild changed layers.
Who It Is For: Teams with frequent Docker builds—microservices, containerized web apps, ML/LLM services—who want faster feedback without losing confidence in their CI/CD pipelines.
Core Problem Solved: Slow, repetitive Docker builds that drag pipeline time and block fast, safe deploys.

How It Works

CircleCI’s Docker Layer Caching keeps a cache of layers built during docker build steps and reuses them across job runs. When the next pipeline runs, Docker pulls cached layers instead of rebuilding everything from scratch, as long as the Dockerfile and build context haven’t changed in ways that invalidate the cache.

In practice, you enable DLC on jobs that run in Docker-enabled executors and build images (for example, pushing to a registry or building an image for later deployment). CircleCI then:

Captures layers: When a job runs a docker build, the resulting layers are stored in a cache tied to that job/executor environment.
Reuses layers: On later runs, the job reuses any unchanged layers, so only the changed parts of the image are rebuilt.
Speeds up pipelines: With layers reused, Docker builds complete much faster, letting you ship trusted container changes at AI speed without sacrificing test/validation.

Enabling Docker Layer Caching in CircleCI

The exact syntax can vary by executor type and plan, but the conceptual steps are the same: use a Docker-capable executor and turn on the docker_layer_caching flag where supported.

1. Use a Docker-capable executor

DLC is relevant when you’re doing docker build inside your job. That typically means:

Machine executor (best for privileged Docker builds)
Docker executor with DinD (docker-in-docker) where supported

Your job might look like:

jobs:
  build-image:
    machine:
      image: ubuntu-2204:current
      docker_layer_caching: true
    steps:
      - checkout
      - run: docker build -t my-app:${CIRCLE_SHA1} .
      - run: docker push my-registry/my-app:${CIRCLE_SHA1}

Key point: you’re running Docker commands in the job, not just using a pre-built image to run tests.

2. Enable Docker Layer Caching on the executor

Within the job definition, you enable DLC using the executor configuration (example above for machine). For a Docker executor variant that supports DLC, it typically looks like:

jobs:
  build-image:
    docker:
      - image: cimg/base:stable
    resource_class: large   # example
    docker_layer_caching: true
    steps:
      - checkout
      - setup_remote_docker:
          docker_layer_caching: true
      - run: docker build -t my-app:${CIRCLE_SHA1} .

Implementation details:

docker_layer_caching: true must be set on the relevant Docker environment setup.
You still define your normal steps (checkout, build, test, push).
DLC doesn’t change your Dockerfile; it just preserves and reuses the layers.

Always verify in the current CircleCI docs which executors and images support DLC, as availability can differ by plan and stack.

3. Target the right jobs

You don’t have to turn DLC on everywhere. For control and cost efficiency:

Enable DLC on jobs with expensive Docker builds (large images, multiple RUN/COPY layers, heavy language runtimes).
Skip DLC on simple test jobs that don’t run docker build.

Example workflow:

workflows:
  version: 2.1
  build_and_test:
    jobs:
      - build-image   # DLC enabled here
      - unit-tests    # no Docker build, no DLC needed

This keeps DLC scoped to the jobs where it delivers real time savings, which is where the billing model pays off.

How Docker Layer Caching Is Billed / Charged

CircleCI pricing for DLC is straightforward and usage-based.

Per-job cost: Docker layer caching uses 200 credits per job run in a pipeline.
Dollar equivalent: 200 credits ≈ $0.12 per job run.
In addition to compute: These credits are on top of your normal compute credits per minute and any network/storage usage.

Concrete billing example

Imagine you have a workflow with three parallel Docker build jobs, all using DLC:

workflows:
  version: 2.1
  docker_builds:
    jobs:
      - build-service-a
      - build-service-b
      - build-service-c

Each job has DLC enabled and runs once per pipeline:

3 jobs × 200 credits = 600 DLC credits per pipeline run
That 600 credits is added to:
- The compute credits (per-minute usage) for each job
- Any network/storage credits (e.g., caches, workspaces, artifacts) beyond free thresholds

If you trigger that workflow 10 times per day:

10 runs × 600 DLC credits = 6,000 DLC credits per day
(plus whatever you spend on compute and network/storage)

Relationship to storage & network

From CircleCI’s billing model:

Storage & network beyond monthly thresholds are charged at 420 credits per GB (~$0.252/GB).
DLC is a separate line item: 200 credits per DLC-enabled job run, not per GB.

So your total monthly cost for a DLC-heavy setup is:

Compute credits (per-minute usage)
- 200 credits per DLC-enabled job run
- 420 credits/GB for network/storage beyond included thresholds

How It Works (Step-by-Step in a Pipeline)

Think of DLC as a stability feature for Docker builds inside your CI/CD pipeline. Here’s how it plays out across builds:

First build (cold cache):
- docker build runs with no previous layers available.
- All layers are built from scratch.
- CircleCI stores the resulting layers in DLC for that job/executor.
Subsequent builds (warm cache):
- On the next pipeline run, DLC makes those layers available.
- Docker reuses all layers whose commands and context haven’t changed.
- Only changed layers are rebuilt, often cutting build time dramatically.
Ongoing development:
- As AI agents or devs push more frequent changes, the cache adapts.
- Reordering instructions in your Dockerfile or changing early layers can invalidate more of the cache; keeping stable layers near the top maximizes reuse.
- You keep short feedback loops even as images evolve.

Because this is happening inside a job in your pipeline, you still have full control:

You can gate Docker build jobs behind approvals.
You can enforce policy checks before Docker build jobs execute.
You can wire successful image builds directly into deploy and rollback pipelines.

Features & Benefits Breakdown

Core Feature	What It Does	Primary Benefit
Persistent Docker layer reuse	Saves built layers between job runs where DLC is enabled	Cuts Docker build times and keeps pipelines fast
Job-level configuration	Lets you toggle DLC per job/executor in your config	Control where you spend DLC credits; enable only where needed
Works with parallel workflows	Applies DLC per job in parallel Docker build workflows	Scales to microservices and multi-image builds without chaos

Ideal Use Cases

Best for microservices and heavy Docker builds:
Because it keeps layer reuse high when many small services share base images and similar dependencies, so you keep AI-speed iteration without ballooning build times.
Best for ML/AI and LLM workloads with large images:
Because those images often have large frameworks and dependencies that rarely change. DLC prevents you from repeatedly rebuilding multi-GB layers every pipeline run.

Limitations & Considerations

Per-job cost add-on:
DLC is not included in compute minutes; it’s an additional 200 credits per job run. Use it where build time savings justify the spend, not in every job.
Cache behavior depends on Dockerfile discipline:
If you frequently change early layers or your Dockerfile is poorly structured (e.g., big COPY . . early on), cache reuse drops. Organize your Dockerfile (stable base and dependencies first, application code later) to maximize DLC effectiveness.

Other practical considerations:

DLC availability and exact configuration flags can vary by plan and executor type; always confirm in current CircleCI docs.
DLC optimizes build time, not runtime performance; you still need solid testing and policy checks to protect production.

Pricing & Plans

CircleCI runs on a usage-based model: you pay in credits for compute time, DLC usage, and any network/storage above included thresholds.

Relevant details for DLC:

Docker Layer Caching:
- 200 credits per job run with DLC enabled
- ≈ $0.12 per DLC-enabled job run
Network & Storage beyond thresholds:
- 420 credits per GB (≈ $0.252/GB)

You can mix and match:

Use larger resource classes plus DLC on critical build jobs for maximum speed.
Keep smaller resource classes and no DLC on lightweight test jobs.

Typical patterns:

Team/Performance-style plans:
- DLC often used on shared “build-and-push” jobs that feed downstream test/deploy workflows.
Enterprise-scale setups:
- Platform teams define golden path jobs with DLC (e.g., standard Docker build jobs).
- Product teams consume these via reusable config, getting DLC speedups without managing billing details directly.

Since DL C is billed per job, tuning your workflows to consolidate heavy Docker builds into fewer, well-structured jobs can reduce DLC spend while preserving speed.

Plan A (DLC-light): Best for teams mainly running tests with only occasional Docker builds. Enable DLC only on the one or two long-running image build jobs.
Plan B (DLC-heavy): Best for microservice organizations or container platforms that build many images per day and want consistently fast builds, accepting higher DLC usage in exchange for shorter pipelines.

Frequently Asked Questions

Do I pay for Docker Layer Caching even if a pipeline is canceled or fails?

Short Answer: Yes, DLC credits apply per job run when DLC is enabled, regardless of success or failure.

Details: The charge is tied to the job starting with DLC enabled, not to the job outcome. If a job with DLC runs—even if it fails due to a test or is manually canceled—you’ll still see the 200-credit DLC usage for that job, plus any compute credits used up to that point.

Does Docker Layer Caching replace normal caching or workspaces?

Short Answer: No. DLC is specifically for Docker image layers; it complements, rather than replaces, caches and workspaces.

Details: CircleCI has several storage mechanisms:

DLC: Persists Docker image layers between job runs where Docker builds occur.
Caches: Save dependency directories (e.g., ~/.m2, node_modules) keyed by checksums.
Workspaces: Pass built artifacts and files between jobs in a workflow.
Artifacts: Persist build outputs (e.g., test reports, binaries) for later inspection.

DLC only affects Docker builds. You’ll usually combine DLC with dependency caches and workspaces for a full-speed pipeline: dependencies install faster, Docker builds reuse layers, and downstream jobs reuse artifacts, all while remaining governed by the same policy checks and approvals.

Summary

Docker Layer Caching in CircleCI is a straightforward way to make Docker builds feel instant again, even as AI-driven development increases change volume. You enable it per job on Docker-capable executors, and CircleCI takes care of reusing layers between runs so you aren’t rebuilding the world on every commit.

From a billing perspective, it’s predictable and usage-based: 200 credits per DLC-enabled job run (about $0.12), on top of your compute minutes and any extra network/storage. When you reserve DLC for the jobs with the heaviest Docker builds, you get a strong tradeoff: shorter pipelines, faster feedback, and enterprise-grade control over where you spend.

Next Step

Get Started