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

Most teams turn on Docker Layer Caching (DLC) in CircleCI for one reason: faster, more predictable Docker builds without trading away confidence. If you’re building containers on every commit or running large multi-stage Dockerfiles, DLC can shave minutes off each job and dramatically reduce delivery drag—especially at AI-era commit volume.

Quick Answer: Docker Layer Caching in CircleCI is an optional job-level setting that persists Docker build layers between job runs so your builds reuse unchanged layers instead of rebuilding from scratch. It’s billed per job run at a flat rate of 200 credits per job (about $0.12 per job) on top of your normal compute usage.

The Quick Overview

What It Is: A CircleCI feature that caches intermediate Docker image layers between job runs, so docker build can reuse prior layers instead of rebuilding every step.
Who It Is For: DevOps, platform, and app teams that run Docker builds frequently in CI—microservices, containers for K8s, large monorepos, mobile backends, and AI/LLM apps packaged as containers.
Core Problem Solved: Slow, repetitive Docker builds that rebuild unchanged layers on every commit, wasting minutes of compute and delaying feedback.

How It Works

DLC plugs into your existing Docker build jobs inside CircleCI workflows. When a job with DLC enabled runs, CircleCI stores the Docker layers produced during docker build. On subsequent runs of that same job (for the same project and executor), CircleCI restores those layers before your build starts. Docker’s native caching kicks in, skips unchanged steps, and only rebuilds what actually changed.

At a high level:

You enable DLC on the job:
In your .circleci/config.yml, you switch to a supported executor (like a machine executor with Docker) and turn on docker_layer_caching: true for the job that runs the Docker build.
CircleCI saves Docker layers after the build:
When the job finishes, CircleCI persists the Docker layers created during docker build. These layers are tied to that project and job context, not shared globally.
Later runs restore layers and speed up builds:
When the job runs again, CircleCI restores the cached layers before your build, so Docker skips unchanged steps. You get faster builds and more consistent timings, especially when most of your Dockerfile stays stable.

Enabling Docker Layer Caching in Your Config

The exact steps depend on your executor, but the pattern is consistent: you enable DLC per job, not globally.

1. Use a DLC‑compatible executor

DLC is designed for jobs that build Docker images. In practice, you’ll typically:

Use a machine executor that supports Docker
Or use the remote Docker environment (for older configs) when available

If you’re moving from a simple Docker executor that just runs containers (no docker build), you may need to switch that job to a machine executor so you can build Docker images and leverage DLC.

Example with machine executor:

version: 2.1

jobs:
  build-docker-image:
    machine:
      image: ubuntu-2204:current
      docker_layer_caching: true
    steps:
      - checkout
      - run:
          name: Build Docker image
          command: |
            docker build -t my-app:${CIRCLE_SHA1} .
      - run:
          name: Push image
          command: |
            docker push my-app:${CIRCLE_SHA1}

workflows:
  build_and_push:
    jobs:
      - build-docker-image

Key detail: docker_layer_caching: true is set on the executor block for that job.

2. Enable DLC in jobs using remote Docker (legacy pattern)

For older configurations that rely on setup_remote_docker, DLC can be enabled in that context when supported:

jobs:
  build-docker-image:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - setup_remote_docker:
          docker_layer_caching: true
      - run:
          name: Build Docker image
          command: |
            docker build -t my-app:${CIRCLE_SHA1} .

Here, DLC is tied to the remote Docker environment that runs your docker build commands.

3. Target only the jobs that actually build images

DLC is charged per job run, so you generally:

Enable DLC only on jobs that:
- Run docker build or build multi-stage images
- Are performance bottlenecks (slow builds, lots of unchanged layers)
Leave it off for jobs that:
- Just run tests inside containers, but don’t build images
- Don’t invoke Docker at all

That’s usually a handful of “docker build & push” jobs across your workflows—not every job in the pipeline.

How Docker Layer Caching Is Billed/Charged

CircleCI uses a usage‑based pricing model. DLC sits on top of your normal compute billing and is charged per job run:

200 credits per job run that uses DLC
This is equivalent to $0.12 per job run
You pay this in addition to the compute credits per minute for that job

From the official docs:

Docker layer caching uses 200 credits per job run in a pipeline (equivalent to $0.12 per job run). For example, if your configuration specifies a workflow with three parallel Docker build jobs, you will be charged 600 credits each time these jobs are run in addition to the compute credits per minute usage.

Concrete billing example

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

workflows:
  docker_pipeline:
    jobs:
      - build-service-a
      - build-service-b
      - build-service-c

Each job has docker_layer_caching: true. On each workflow run:

DLC cost:
- 3 jobs × 200 credits = 600 credits of DLC charges
Plus compute cost:
- Whatever credits-per-minute you’re paying for the selected resource class × job runtime

If you run that workflow 100 times in a month:

DLC total = 600 credits × 100 = 60,000 credits for DLC
Compute cost depends on your resource classes and job durations

This model makes DLC very predictable: flat rate per job, no hidden GB‑based DLC billing.

How DLC fits with other usage charges

DLC is separate from:

Compute credits per minute (based on resource class like Linux Medium, large, etc.)
Network and storage charges:
- Activities like caches, workspaces, test results, and artifacts use storage
- Network and storage beyond included thresholds are charged at 420 credits per GB (~$0.252/GB)

DLC doesn’t consume network/storage billing directly; its cost is the per‑job 200 credits.

Features & Benefits Breakdown

Core Feature	What It Does	Primary Benefit
Persistent Docker layers	Saves Docker image layers between job runs for the same project and executor	Cuts rebuild time by reusing unchanged steps in your Dockerfile.
Job-level configuration	Enabled via `docker_layer_caching: true` on specific jobs or remote Docker	Lets you spend credits only where builds are slow and cache-friendly.
Consistent build performance	Reuses prior layers, stabilizing build times even as commit volume increases	Keeps pipelines responsive at AI speed without noisy, long builds.

Ideal Use Cases

Best for container-heavy microservices:
Because each service often shares a large portion of its Dockerfile (base image, language runtime, dependencies). DLC lets you cache those layers and only rebuild the parts that changed, keeping parallel Docker build jobs fast and predictable.
Best for large, multi-stage Dockerfiles:
Because multi-stage builds frequently install OS packages, language runtimes, and tooling that rarely change. DLC ensures those expensive layers are reused, shortening the feedback loop on code changes while keeping the build pipeline trusted and reproducible.

Limitations & Considerations

Per-job cost adds up with many builds:
DLC is charged at 200 credits per job run, regardless of how much time or data it saves. If you enable it on every job in a large, high-frequency pipeline, you can drive up credit usage quickly. The practical workaround is to enable DLC only on high-impact Docker build jobs and monitor usage in your CircleCI billing dashboard.
Cache is not a deployment artifact:
DLC accelerates Docker builds but does not replace storing published images in a registry (ECR, GCR, Docker Hub, etc.). You still need a proper image registry for trusted, versioned deploy artifacts and rollback pipelines.

Pricing & Plans

DLC is a feature charged via credits, not a separate plan tier. As long as you’re on a credits‑based plan (for example, the Performance Plan), you can enable DLC on eligible jobs and pay for what you use.

Remember:

DLC: 200 credits per job run (~$0.12 per job)
Network/storage beyond included thresholds: 420 credits per GB (~$0.252/GB)
You still pay your normal compute credits per minute based on resource class

Because CircleCI emphasizes powerful resources and concurrency, you typically get more work done per credit compared to running the same Docker builds on underpowered agents. In practice, DLC pairs well with parallel builds and larger resource classes: you pay a small fixed DLC fee and run high-throughput, cache‑friendly builds.

Example positioning:

Performance / usage-based plan:
Best for teams that want to tune where DLC is enabled and maximize value—enabling it only on the slowest Docker build jobs that gate deploys.
Higher-volume / enterprise plans:
Best for organizations standardizing Docker builds across many services, where platform teams can define golden paths that include DLC on common “build and push” jobs and enforce policy checks before execution.

(Exact plan names and inclusions can change; check CircleCI’s current pricing page for your account type.)

Frequently Asked Questions

How do I decide which jobs should use Docker Layer Caching?

Short Answer: Turn on DLC only for jobs that actually run docker build and have slow, repetitive builds with mostly stable Dockerfile layers.

Details:
Start by profiling your pipelines:

Identify jobs that:
- Run docker build or multi-stage Docker builds
- Take significantly longer than your test jobs
- Have stable steps (install OS packages, language runtimes, tooling, base dependencies)
Enable docker_layer_caching: true only on those jobs.
Watch job duration over a few days. If you’re not seeing a meaningful drop in build time, consider disabling DLC for that job to save credits.

The sweet spot is where DLC eliminates rebuilds of expensive layers (like RUN apt-get install ... or RUN npm ci on rarely changing lockfiles) while letting you keep a tight, trusted Docker build loop.

Does Docker Layer Caching change how my builds run or affect reliability?

Short Answer: No. DLC doesn’t change your Dockerfile or pipeline logic; it just gives Docker more cached layers to use.

Details:
With DLC enabled:

Your Dockerfile remains the source of truth. Docker still respects cache invalidation rules (layer hashes, changed files, etc.).
If you change a layer—like modifying a RUN command or the files it touches—Docker rebuilds that layer and everything after it, just as it would without DLC.
If you’re worried about stale layers, you can:
- Periodically invalidate cache by changing a base layer or using --no-cache when needed
- Introduce explicit cache-busting steps (e.g., environment variables or build args)

From a reliability standpoint, DLC helps stabilize build times and makes rebuild behavior more predictable, but it doesn’t bypass the checks you’ve built into your pipeline—tests, approvals, and policy checks still run as usual.

Summary

Docker Layer Caching in CircleCI is a targeted acceleration feature: you enable it on the Docker build jobs that gate your releases, and CircleCI persists image layers between runs so docker build only rebuilds what changed. It’s billed simply—200 credits per job run (~$0.12) on top of normal compute credits—so you can model ROI quickly and turn it on where it matters most.

Used well, DLC helps you ship containers at AI speed without sacrificing the trust you have in your builds: faster Docker jobs, consistent pipelines, and more time spent on actual changes instead of waiting for base layers to reinstall on every commit.

Next Step

Get Started