How to Cache Docker Layers in Bitbucket Pipelines

By Daniel Zoghalchali·Latchkey

Bitbucket has a built-in docker cache for the layer store, plus registry-backed Buildx caching for cross-run reuse.

Add the predefined docker cache to a step to persist the local layer store, or push a registry cache with Buildx for reuse across branches and runners.

Built-in docker cache on a step

The docker cache persists the daemon's layer store between runs of this step.

pipelines:
  default:
    - step:
        name: Build image
        services:
          - docker
        caches:
          - docker
        script:
          - docker build -t app:$BITBUCKET_COMMIT .

Gotchas

• The built-in docker cache caches the local layer store; for cross-branch reuse, push a registry cache with Buildx instead.
• Building images requires the docker service on the step, or docker build has no daemon.
• Bitbucket caches expire after 7 days and have a size cap; very large layer stores may not fully persist.

Verify it actually works

Bitbucket validates bitbucket-pipelines.yml on push, and a schema error disables the pipeline rather than failing a build, which can look like nothing happened at all.

# validate before pushing
curl -X POST -H "Content-Type: application/x-yaml" \
  --data-binary @bitbucket-pipelines.yml \
  https://api.bitbucket.org/2.0/repositories/<workspace>/<repo>/pipelines/validate

# confirm which pipeline definition matched
# Pipelines -> the run -> "Configuration" tab

Constraints that catch people out

• Each step runs in a fresh container. Nothing persists between steps unless it is declared as an artifact or a cache.
• The default memory allocation per step is limited, and service containers share that budget, so adding a database service can push a previously passing build into an out-of-memory failure.
• Only branches with a matching branches: definition run; a push to an unmatched branch silently runs nothing.
• Artifacts are passed forward only to later steps in the same pipeline, not between pipelines.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation