List a Container's Saved States with docker checkpoint ls

You saved a checkpoint last week and now cannot remember what you called it. docker checkpoint ls lists the saved checkpoints belonging to one container, with an optional alternate checkpoint directory. The command is read-only: it does not create, restore or remove anything. Allow about ten minutes if Docker and the container are already available.

This guide describes Docker CE CLI 29.8.1, package version 5:29.8.1-1~ubuntu.24.04~noble, installed on this machine. Checkpoint and Restore is an experimental Docker feature, and the exact support available depends on the Docker daemon and its host kernel. The installed manual page documents one option only: --checkpoint-dir.

1. Confirm the command and its prerequisite

Start by checking which Docker client will run. This does not contact the daemon or change any Docker state:

$ command -v docker
/usr/bin/docker
$ docker version --format '{{.Client.Version}}'
29.8.1

The client must talk to a Docker daemon with experimental features enabled. On this installation, asking for help without that daemon capability produces this error:

$ docker checkpoint ls --help
docker checkpoint ls is only supported on a Docker daemon with experimental features enabled

That message is a prerequisite failure, not evidence that the container has no checkpoints. Checkpoint commands also depend on CRIU, the external checkpoint and restore implementation.

Warning: Do not enable experimental features or install CRIU just to make a listing command pass, unless you own the daemon and have reviewed the operational consequences.

2. List checkpoints for a container

Provide a container name or ID in place of CONTAINER_NAME:

$ docker checkpoint ls CONTAINER_NAME

A successful command prints the checkpoints known for that container. The exact table and column formatting is supplied by the Docker CLI and daemon, so use the exit status as the machine-readable success signal rather than scraping whitespace. An empty result means there are no checkpoints in the directory Docker is using, assuming the command completed successfully.

If you are testing it in a script, capture the status immediately after the list command:

$ docker checkpoint ls CONTAINER_NAME
$ status=$?
$ printf 'docker checkpoint ls exited with %s\n' "$status"
docker checkpoint ls exited with 0

Checkpoint: You should see an exit status of 0. Replace the placeholder before running the command: a name or ID that does not identify a usable container can produce a daemon error, but the installed CLI may fail earlier when experimental support is disabled.

3. Use a custom checkpoint directory

Pass --checkpoint-dir when the checkpoints are stored outside Docker's normal location:

$ docker checkpoint ls --checkpoint-dir /srv/docker-checkpoints CONTAINER_NAME

The option selects the directory to inspect. It does not create the directory, migrate checkpoint data or change the daemon's default. Use the same directory convention that was used when the checkpoint was created.

Tip: A path containing no matching checkpoint data can look like a successful empty list. Check the directory before troubleshooting Docker output:

$ test -d /srv/docker-checkpoints && echo 'directory exists'
directory exists
$ test -r /srv/docker-checkpoints && echo 'directory is readable'
directory is readable

These tests only inspect the path. They do not prove that it contains a valid checkpoint for the selected container, but they separate a missing or unreadable path from an ordinary empty result.

4. Handle privilege and daemon errors

Run the listing as your normal account first. Docker access commonly depends on the account's access to the Docker socket, and using elevated privileges changes which client configuration and daemon endpoint are in play.

$ docker checkpoint ls CONTAINER_NAME
permission denied while trying to connect to the Docker daemon socket

The wording can vary by Docker release. If the command cannot connect, check the active context and daemon status using your host's normal administrative process. Only use sudo when your Docker access policy explicitly requires it:

$ sudo docker checkpoint ls CONTAINER_NAME

Security warning: Do not add sudo automatically to scripts. It can hide an account or socket configuration problem, and it may use a different Docker context.

A successful listing still does not mean that the checkpoint can be restored on this host.

5. Keep listing separate from destructive operations

docker checkpoint ls only lists checkpoints, and there is no undo operation in it because there is nothing to undo.

Destructive action: Do not substitute docker checkpoint rm while copying an example. Removing a checkpoint can take away the state needed for a later restore.

Warning: Do not use docker checkpoint create as a test either. Creating a checkpoint freezes a running container during the operation and writes state to disk.

If you only need to inspect the available names, stop after the list command. If you need to create or remove checkpoint data, record the container, checkpoint name and storage directory first, then review that separate operation's documentation.

6. Diagnose an unexpected empty list

Work through these checks in order:

  1. Check the daemon. Confirm that the command reached a daemon with experimental features enabled.
  2. Check the container. Confirm that the name or ID identifies the intended container.
  3. Check the directory. Confirm that the custom directory is exactly the one used for the checkpoint.
  4. Check the exit status. Read it, and any error output, separately from the displayed rows.
  5. Check the environment. Verify the checkpoint on the same host and with the same Docker environment that created it.

An empty list is not proof that checkpoint support is broken. It can mean that the selected container has no checkpoints, that the custom directory is wrong, or that the checkpoint data belongs to a different Docker setup.

Conversely, a non-zero exit status is not an empty list. Preserve the error and investigate the prerequisite or access problem.

Done means