How to Cache Docker Layers in CircleCI

CircleCI reuses image layers via Docker Layer Caching (DLC) on the remote Docker env, or via a registry cache with Buildx.

Set docker_layer_caching: true on setup_remote_docker to reuse layers across builds. For finer control, use Buildx on the machine executor with a registry-backed cache.

Enable DLC on remote Docker

DLC keeps a layer cache attached to the remote Docker host, reused on the next run.

jobs:
  build:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - setup_remote_docker:
          docker_layer_caching: true
      - run: docker build -t app:$CIRCLE_SHA1 .

Gotchas

• docker_layer_caching: true is a paid feature on most plans - it errors on plans without DLC enabled.
• DLC caches layers on the remote Docker host, not in the project cache; for cross-host reuse use a registry cache with Buildx.
• Order the Dockerfile so dependency layers precede source-copy layers to maximize the DLC hit rate.

Related guides