Freeze a Running Container with docker checkpoint create

Your container is mid-task, you need to interrupt it, and you would rather not lose its place. This guide uses docker checkpoint create to save a running container's process state under a name, confirm what happened, and restore it later. 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. Treat this as a capability test, not 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 manpage describes two options for docker checkpoint create:

• --checkpoint-dir for custom storage.
• --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 ....

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}}'

What you see depends on the daemon:

• Without experimental features, the installed CLI 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 after a successful command the container is expected to be left stopped or paused, according to the engine's checkpoint workflow.

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.

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.

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

Common traps

• 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.
• No undo. There is no useful edit operation for a checkpoint. To abandon one, stop using it 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.