Create and Restore a Docker Checkpoint Without Losing Your Place

You will create a named checkpoint from a running Docker container, confirm what happened, and restore the container from that saved process state. Allow about 10 minutes if Docker and a suitable test container are already available. Checkpointing depends on CRIU support in the Docker Engine, the kernel, and the container runtime, so treat this as a capability test rather than a portable backup method.

Before you start

This guide targets Docker Community Edition CLI 29.8.1 from the installed docker-ce-cli package. The local command is docker checkpoint create; the manpage describes two options: --checkpoint-dir for custom storage and --leave-running to keep the container running after the checkpoint.

You need a running container that you can safely pause and later restart. You also need permission to talk to the Docker daemon. That usually means membership of the docker group or an elevated command such as sudo docker .... The latter grants the command root-equivalent access to the host, so use it only when the daemon socket requires it.

Do not use a checkpoint as a substitute for an image, volume backup, or database backup. It captures process state and runtime files for a particular container. Keep the original container and its image until you have proved that restoration works.

1. Check the local command and container

First confirm the installed version and choose a real container name. The checkpoint command is gated by Docker's experimental daemon features, so the help command may refuse to run before it prints its options.

docker checkpoint create --help
docker --version
docker ps --format '{{.Names}}\t{{.Status}}'

On the installed CLI, a daemon without experimental features reports that checkpoint creation is supported only when those features are enabled. With the feature available, help includes docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT and the two options from the manpage. Pick a running name and substitute it for APP_CONTAINER below. If the container is not running, checkpoint creation cannot perform the requested operation.

2. Create a checkpoint

Creating a checkpoint normally pauses the running container while Docker saves the process state. The default for --leave-running is false, so the container is expected to be left stopped or paused according to the engine's checkpoint workflow after a successful command. That interruption is the main service-disruption warning in this guide: schedule it like a short maintenance event.

The checkpoint name is an identifier, not a filename. Use a simple name that you will recognise later.

docker checkpoint create APP_CONTAINER before-maintenance

A successful command normally returns no checkpoint details. Verify both the exit status and the container state:

test $? -eq 0 && docker ps -a --filter name=APP_CONTAINER

Replace APP_CONTAINER in the filter with the actual name. If the command fails, do not delete the container or try repeated restores. Read the daemon error first. A CRIU error often identifies a missing kernel feature, an unsupported mount, or a terminal configuration that prevents dumping the process.

3. Find the saved checkpoint

Docker stores checkpoints with the container's runtime data unless you provide another directory. The engine decides the exact internal layout, so do not build automation around a guessed path. Keep the checkpoint name, container name, and creation time in your maintenance notes. Do not edit or move the files while the checkpoint is needed.

To keep the files somewhere specific, create a directory first and pass it explicitly when creating the checkpoint:

mkdir -p /srv/docker-checkpoints/APP_CONTAINER
docker checkpoint create --checkpoint-dir /srv/docker-checkpoints/APP_CONTAINER APP_CONTAINER before-maintenance

The directory must be usable by the Docker daemon, not merely by your interactive shell. A permission error here is about the daemon's access to the path. Keep the directory private: a checkpoint can contain application memory and other sensitive process data.

4. Restore the container

Restoration starts the container from the saved process state rather than launching its command from the beginning. Keep the original image and container configuration available. Use the checkpoint name exactly as it was created:

docker start --checkpoint before-maintenance APP_CONTAINER

Check that Docker reports the container ID or otherwise exits successfully, then inspect its state:

docker ps --filter name=APP_CONTAINER
docker logs --tail 20 APP_CONTAINER

For a test process with a counter or timestamp, the useful result is that execution continues from the saved point. For a real service, verify the service at its own health endpoint and inspect its logs before sending traffic to it.

Common failure points

• External terminals: containers started with an attached terminal, such as docker run -t, may not be checkpointable. Recreate a disposable test container without an external terminal before diagnosing the host.
• Seccomp and kernel support: CRIU support varies with the kernel and configuration. Docker's upstream command documentation specifically calls out seccomp as requiring a sufficiently recent kernel. Do not weaken host security policy on a production container just to make a checkpoint pass.
• Custom storage: --checkpoint-dir changes where checkpoint data is written, not the container's writable layer or its volumes. Back up those data stores separately.
• Wrong expectation about undo: there is no useful edit operation for a checkpoint. To abandon it, stop using that checkpoint and remove it with the checkpoint management command available on your Docker installation, after confirming that no restore depends on it. Keep the container itself until the replacement checkpoint is tested.