Sitelet https://github.com/docker/docs/pull/26307/files
Skip to content

engine/storage/containerd: Document lazy pulling #26307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vvoland merged 1 commit into from
Oct 8, 2026
+43 −0
Merged

engine/storage/containerd: Document lazy pulling #26307

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions _vale/config/vocabularies/Docker/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,7 @@ Sonoma
Splunk
SQLite
stargz
eStargz
stdin
stdout
subfolder
Expand Down
42 changes: 42 additions & 0 deletions content/manuals/engine/storage/containerd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,48 @@ Docker Engine uses the `overlayfs` containerd snapshotter by default.
> image store, push them to a registry first, or use `docker save` to export
> them.

## Lazy pulling

With lazy pulling, containers can start before their images are fully downloaded.
Remote snapshotters fetch layer data from the registry as containers need it.

Docker Engine enables lazy pulling by default when configured to use the `nydus`, `overlaybd`, `soci`, or `stargz` snapshotter.
With other snapshotters, including the default `overlayfs`, Docker downloads all layer content before the container starts unless you explicitly enable lazy pulling.

During a lazy pull, Docker skips downloading a layer if the snapshotter can mount it remotely or already has its snapshot.
Docker downloads all other layers.
For example, the stargz snapshotter can mount eStargz layers remotely, but plain gzip layers must be downloaded unless their snapshots already exist.

### Saving and pushing images

Lazily pulled images can run even if some layer content is missing from the containerd content store.
However, missing content affects saving and pushing:

- `docker save` can fail or produce an incomplete archive without reporting an error.
- `docker push` cannot upload missing layers, but can reuse them if the target registry supports mounting them from the source repository.

Running the image is not guaranteed to fill in the missing content in the containerd content store.
For example, the stargz snapshotter keeps the data it fetches in its own cache.
See [moby#53878](https://github.com/moby/moby/issues/53878) for details.

### Configuration

To disable lazy-pulling, set the `lazy-pull` feature to `false` in `/etc/docker/daemon.json`:

```json
{
"features": {
"containerd-snapshotter": true,
"lazy-pull": false
}
}
```

Reload the daemon configuration to apply the setting to subsequent pulls.
For images you already pulled lazily, pull them again to download the missing content.

To enable lazy pulling for a snapshotter outside the default list, set `lazy-pull` to `true` instead.

## Experimental automatic migration

Docker Engine includes an experimental feature that can automatically switch to
Expand Down