docker · dvdksn · Nov 18, 2025 · Nov 13, 2025 · Nov 13, 2025
diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt
@@ -161,6 +161,7 @@ pgAdmin
 PKG
 plaintext
 plist
+pluggable
 Postgres
 PowerShell
 Python
@@ -183,6 +184,7 @@ Solr
 SonarQube
 Splunk
 SQLite
+stargz
 stdin
 stdout
 subfolder

@@ -98,24 +98,44 @@ The Docker daemon persists all data in a single directory. This tracks
 everything related to Docker, including containers, images, volumes, service
 definition, and secrets.
 
-By default this directory is:
+By default the daemon stores data in:
 
-- `/var/lib/docker` on Linux.
-- `C:\ProgramData\docker` on Windows.
+- `/var/lib/docker` on Linux
+- `C:\ProgramData\docker` on Windows
 
-You can configure the Docker daemon to use a different directory, using the
-`data-root` configuration option. For example:
+When using the [containerd image store](/manuals/engine/storage/containerd.md)
+(the default for Docker Engine 29.0 and later on fresh installations), image
+contents and container snapshots are stored in `/var/lib/containerd`. Other
+daemon data (volumes, configs) remains in `/var/lib/docker`.
+
+When using [classic storage drivers](/manuals/engine/storage/drivers/_index.md)
+like `overlay2` (the default for upgraded installations), all data is stored in
+`/var/lib/docker`.
+
+### Configure the data directory location
+
+You can configure the Docker daemon to use a different storage directory using
+the `data-root` configuration option.
 
 ```json
 {
   "data-root": "/mnt/docker-data"
 }
 ```
 
-Since the state of a Docker daemon is kept on this directory, make sure you use
-a dedicated directory for each daemon. If two daemons share the same directory,
-for example, an NFS share, you are going to experience errors that are difficult
-to troubleshoot.
+The `data-root` option does not affect image and container data stored in
+`/var/lib/containerd` when using the containerd image store. To change the
+storage location of containerd snapshotters, use the system containerd
+configuration file:
+
+```toml {title="/etc/containerd/config.toml"}
+version = 2
+root = "/mnt/containerd-data"
+```
+
+Make sure you use a dedicated directory for each daemon. If two daemons share
+the same directory, for example an NFS share, you will experience errors that
+are difficult to troubleshoot.
 
 ## Next steps
 

@@ -8,6 +8,22 @@ aliases:
   - /storage/
 ---
 
+Docker storage covers two different concepts:
+
+**Container data persistence** (this page): How to store application data
+outside containers using volumes, bind mounts, and tmpfs mounts. This data
+persists independently of container lifecycle.
+
+**Daemon storage backends** ([containerd image store](containerd.md) and
+[storage drivers](drivers/)): How the daemon stores image layers and container
+writable layers on disk.
+
+This page focuses on container data persistence. For information about how
+Docker stores images and container layers, see
+[containerd image store](containerd.md) or [Storage drivers](drivers/).
+
+## Container layer basics
+
 By default all files created inside a container are stored on a writable
 container layer that sits on top of the read-only, immutable image layers.
 
@@ -78,9 +94,13 @@ Docker Engine API using a named pipe.
 
 ## Next steps
 
-- Learn more about [volumes](./volumes.md).
-- Learn more about [bind mounts](./bind-mounts.md).
-- Learn more about [tmpfs mounts](./tmpfs.md).
-- Learn more about [storage drivers](/engine/storage/drivers/), which
-  are not related to bind mounts or volumes, but allow you to store data in a
-  container's writable layer.
+Learn more about container data persistence:
+
+- [Volumes](./volumes.md)
+- [Bind mounts](./bind-mounts.md)
+- [tmpfs mounts](./tmpfs.md)
+
+Learn more about daemon storage backends:
+
+- [containerd image store](containerd.md)
+- [Storage drivers](drivers/)
@@ -3,54 +3,131 @@
 linkTitle: containerd image store
 weight: 50
 keywords: containerd, snapshotters, image store, docker engine
-description: Learn how to enable the containerd image store on Docker Engine
+description: Learn about the containerd image store
 aliases:
   - /storage/containerd/
 ---
 
-{{< summary-bar feature_name="containerd" >}}
+The containerd image store is the default storage backend for Docker Engine
+29.0 and later on fresh installations. If you upgraded from an earlier version,
+your daemon continues using the legacy graph drivers (overlay2) until you
+enable the containerd image store.
 
 containerd, the industry-standard container runtime, uses snapshotters instead
-of the classic storage drivers for storing image and container data.
-While the `overlay2` driver still remains the default driver for Docker Engine,
-you can opt in to using containerd snapshotters as an experimental feature.
+of classic storage drivers for storing image and container data.
 
-To learn more about the containerd image store and its benefits, refer to
-[containerd image store on Docker Desktop](/manuals/desktop/features/containerd.md).
+> [!NOTE]
+> The containerd image store is not available when using user namespace
+> remapping (`userns-remap`). See
+> [moby#47377](https://github.com/moby/moby/issues/47377) for details.
+
+## Why use the containerd image store
+
+The containerd image store uses snapshotters to manage how image layers are
+stored and accessed on the filesystem. This differs from the classic graph
+drivers like overlay2.
+
+The containerd image store enables:
+
+- Building and storing multi-platform images locally. With classic storage
+  drivers, you need external builders for multi-platform images.
+- Working with images that include attestations (provenance, SBOM). These use
+  image indices that the classic store doesn't support.
+- Running Wasm containers. The containerd image store supports WebAssembly
+  workloads.
+- Using advanced snapshotters. containerd supports pluggable snapshotters that
+  provide features like lazy-pulling of images (stargz) or peer-to-peer image
+  distribution (nydus, dragonfly).
+
+For most users, switching to the containerd image store is transparent. The
+storage backend changes, but your workflows remain the same.
 
 ## Enable containerd image store on Docker Engine
 
-Switching to containerd snapshotters causes you to temporarily lose images and
-containers created using the classic storage drivers.
-Those resources still exist on your filesystem, and you can retrieve them by
-turning off the containerd snapshotters feature.
+If you're upgrading from an earlier Docker Engine version, you need to manually
+enable the containerd image store.
 
-The following steps explain how to enable the containerd snapshotters feature.
+> [!IMPORTANT]
+> Switching storage backends temporarily hides images and containers created
+> with the other backend. Your data remains on disk. To access the old images
+> again, switch back to your previous storage configuration.
 
-1. Add the following configuration to your `/etc/docker/daemon.json`
-   configuration file:
+Add the following configuration to your `/etc/docker/daemon.json` file:
 
-   ```json
-   {
-     "features": {
-       "containerd-snapshotter": true
-     }
-   }
-   ```
+```json
+{
+  "features": {
+    "containerd-snapshotter": true
+  }
+}
+```
 
-2. Save the file.
-3. Restart the daemon for the changes to take effect.
+Save the file and restart the daemon:
 
-   ```console
-   $ sudo systemctl restart docker
-   ```
+```console
+$ sudo systemctl restart docker
+```
 
-After restarting the daemon, running `docker info` shows that you're using
-containerd snapshotter storage drivers.
+After restarting the daemon, verify you're using the containerd image store:
 
 ```console
 $ docker info -f '{{ .DriverStatus }}'
 [[driver-type io.containerd.snapshotter.v1]]
 ```
 
 Docker Engine uses the `overlayfs` containerd snapshotter by default.
+
+> [!NOTE]
+> When you enable the containerd image store, existing images and containers
+> from the overlay2 driver remain on disk but become hidden. They reappear if
+> you switch back to overlay2. To use your existing images with the containerd
+> image store, push them to a registry first, or use `docker save` to export
+> them.
+
+## Experimental automatic migration
+
+Docker Engine includes an experimental feature that can automatically switch to
+the containerd image store under certain conditions. **This feature is
+experimental**. It's provided for those who want to test it, but [starting
+fresh](#enable-containerd-image-store-on-docker-engine) is the recommended
+approach.
+
+> [!CAUTION]
+> The automatic migration feature is experimental and may not work reliably in
+> all scenarios. Create backups before attempting to use it.
+
+To enable automatic migration, add the `containerd-migration` feature to your
+`/etc/docker/daemon.json`:
+
+```json
+{
+  "features": {
+    "containerd-migration": true
+  }
+}
+```
+
+You can also set the `DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD` environment
+variable to make the daemon switch automatically if you have no containers and
+your image count is at or below the threshold. For systemd:
+
+```console
+$ sudo systemctl edit docker.service
+```
+
+Add:
+
+```ini
+[Service]
+Environment="DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD=5"
+```
+
+If you have no running or stopped containers and 5 or fewer images, the daemon
+switches to the containerd image store on restart. Your overlay2 data remains
+on disk but becomes hidden.
+
+## Additional resources
+
+To learn more about the containerd image store and its capabilities in Docker
+Desktop, see
+[containerd image store on Docker Desktop](/manuals/desktop/features/containerd.md).
@@ -1,6 +1,6 @@
 ---
 description: Learn the technologies that support storage drivers.
-keywords: container, storage, driver, btrfs, overlayfs, vfs, zfs
+keywords: container, storage, driver, btrfs, overlayfs, vfs, zfs, containerd
 title: Storage drivers
 weight: 40
 aliases:
@@ -9,6 +9,16 @@ aliases:
   - /engine/userguide/storagedriver/imagesandcontainers/
 ---
 
+> [!NOTE]
+> Docker Engine 29.0 and later uses the
+> [containerd image store](../containerd.md) by default for fresh installations.
+> The containerd image store uses snapshotters instead of the classic storage
+> drivers described on this page. If you're running a fresh installation of
+> Docker Engine 29.0 or later, or if you've migrated to the containerd image
+> store, this page provides background on how image layers work but the
+> implementation details differ. For information about the containerd image
+> store, see [containerd image store](../containerd.md).
+
 To use storage drivers effectively, it's important to know how Docker builds and
 stores images, and how these images are used by containers. You can use this
 information to make informed choices about the best way to persist data from

@@ -12,13 +12,18 @@ This page refers to the Linux kernel driver as `OverlayFS` and to the Docker
 storage driver as `overlay2`.
 
 > [!NOTE]
->
+> Docker Engine 29.0 and later uses the
+> [containerd image store](/manuals/engine/storage/containerd.md) by default.
+> The `overlay2` driver is a legacy storage driver that is superseded by the
+> `overlayfs` containerd snapshotter. For more information, see
+> [Select a storage driver](/manuals/engine/storage/drivers/select-storage-driver.md).
+
+> [!NOTE]
 > For `fuse-overlayfs` driver, check [Rootless mode documentation](/manuals/engine/security/rootless.md).
 
 ## Prerequisites
 
-OverlayFS is the recommended storage driver, and supported if you meet the following
-prerequisites:
+The `overlay2` driver is supported if you meet the following prerequisites:
 
 - Version 4.0 or higher of the Linux kernel, or RHEL or CentOS using
   version 3.10.0-514 of the kernel or higher.