How to Cache Docker Layers to a Local Path With buildx

type=local writes layer cache to a folder you then persist with actions/cache between runs.

Export cache with cache-to: type=local,dest=/tmp/.buildx-cache and read it with cache-from: type=local,src=.... Wrap the folder in an actions/cache step so it survives across runs. A move dance avoids unbounded growth.

Steps

• Restore the cache folder with actions/cache before building.
• Build with cache-from/cache-to pointing at local paths.
• Swap the new cache into place so the folder does not grow forever.

Workflow

steps:
  - uses: actions/cache@v4
    with:
      path: /tmp/.buildx-cache
      key: buildx-${{ github.sha }}
      restore-keys: buildx-
  - uses: docker/build-push-action@v6
    with:
      context: .
      cache-from: type=local,src=/tmp/.buildx-cache
      cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
  - run: rm -rf /tmp/.buildx-cache && mv /tmp/.buildx-cache-new /tmp/.buildx-cache

Gotchas

• Without the move step, BuildKit appends and the local cache grows without bound.
• The gha backend is simpler for most repos; local is useful on self-hosted disks.

Related guides