Delete a Saved Container State with docker checkpoint rm

Old checkpoints pile up quietly, and the one you delete had better be the one you meant. docker checkpoint rm removes one named Docker checkpoint and leaves the container and its image in place. Allow about ten minutes, plus time for a checkpoint operation to finish on a busy host.

You need the Docker CLI, access to the relevant daemon, and a checkpoint that you are certain can be discarded.

This guide uses Docker CE CLI 29.8.1, from package docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble. Checkpoint support is experimental. The installed client refuses this command unless it is talking to a daemon with experimental features enabled, and the feature may change or disappear in a later release.

1. Check the installed command

Start with the read-only help output. This confirms that the command expects a container followed by a checkpoint name, and that the only option is a custom storage directory:

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

On a daemon with the feature enabled, the help text also describes the form docker checkpoint rm [OPTIONS] CONTAINER CHECKPOINT. The command has an alias, docker checkpoint remove, but use rm in scripts so the operation is easy to recognise.

Checkpoint removal is a change to Docker state. It normally does not require sudo when your account can access the Docker socket. If it cannot, either use your normal approved privilege method or ask the Docker administrator to perform the operation.

Tip: Do not add sudo merely because the checkpoint is stored below Docker's data directory.

2. Identify the exact checkpoint

List checkpoints for the target container before removing anything. Replace both placeholders with values from your own Docker environment:

$ docker checkpoint ls CONTAINER_NAME_OR_ID
CHECKPOINT NAME        CREATED                 PLATFORM
checkpoint-to-remove   2026-09-23 10:15:22    linux

The columns and timestamp format can vary with the client and daemon. The useful result is the exact checkpoint name associated with the exact container. A checkpoint name belongs in the second positional argument; it is not a container ID, image tag or host directory name.

Checkpoint: Write down the container reference and checkpoint name together. If the list is empty, stop. There is nothing for this command to remove, and inventing a name risks hiding the real problem, such as querying the wrong daemon or container.

3. Remove the checkpoint

Once the identity is confirmed, run the destructive command. The example uses shell variables to make the two arguments visible during review:

$ CONTAINER='CONTAINER_NAME_OR_ID'
$ CHECKPOINT='checkpoint-to-remove'
$ docker checkpoint rm "$CONTAINER" "$CHECKPOINT"

A successful removal normally produces no output and returns status 0. Capture the status if this is part of a script:

$ status=$?
$ printf 'docker checkpoint rm exit status: %s\n' "$status"
docker checkpoint rm exit status: 0

Destructive action: There is no undo option in docker checkpoint rm. Removing the checkpoint discards the saved process state. Keep the checkpoint until you have confirmed that any restore, migration or incident-response work no longer needs it.

What it does not do: it does not stop, remove or recreate the container, and it does not create a replacement checkpoint.

4. Verify that only the intended checkpoint disappeared

List the same container again, using the same storage-directory choice as the removal command:

$ docker checkpoint ls "$CONTAINER"
CHECKPOINT NAME        CREATED                 PLATFORM
checkpoint-to-keep     2026-09-23 10:17:04    linux

Checkpoint: The removed name should no longer appear, and other checkpoints should remain. If the command returns an error, do not assume that a missing line proves success. Check the exit status and resolve the error first.

You can also check that the container still exists without changing it:

$ docker container inspect "$CONTAINER" --format '{{.Id}} {{.State.Status}}'
CONTAINER_ID_HERE running

The identifier and state are host-specific. The point of this check is that checkpoint removal is narrower than docker rm: the container should still be inspectable.

5. Use a custom checkpoint directory consistently

If the checkpoint was created with a custom storage directory, pass that directory to both listing and removal. The directory must be visible to the daemon, not merely to your shell, so use an absolute path that exists in the daemon's environment:

$ CHECKPOINT_DIR='/absolute/path/to/checkpoints'
$ docker checkpoint ls --checkpoint-dir "$CHECKPOINT_DIR" "$CONTAINER"
$ docker checkpoint rm --checkpoint-dir "$CHECKPOINT_DIR" "$CONTAINER" "$CHECKPOINT"
$ docker checkpoint ls --checkpoint-dir "$CHECKPOINT_DIR" "$CONTAINER"

Warning: Do not replace this command with rm -rf on the directory. Docker tracks checkpoint state and the directory can contain checkpoints for more than one container. Deleting files by hand can remove the wrong saved state and bypass daemon checks.

If the directory is on a mounted filesystem, confirm the mount and permissions with your platform administrator before retrying.

6. Handle the common failures

• Experimental features message. The daemon does not expose the required capability. It is not a spelling error in the checkpoint name. Check the client and server details, then enable experimental Docker features only under your normal change process. Do not treat a failed removal as permission to delete the storage directory manually.
• Missing checkpoint error. Usually one of three things: the name was mistyped, the container reference points at a different container, or the command omitted the custom directory. Re-run the matching docker checkpoint ls command and compare the output exactly.
• Permission or socket error. This needs an access fix, not a different checkpoint name.
• Failure after an interruption. If a removal fails after a daemon or host interruption, preserve the directory and collect the Docker daemon error before retrying. Do not repeatedly run a destructive operation while another checkpoint or restore operation is active.

Recovery: The checkpoint feature is experimental, so include the Docker release and runtime details in any escalation.

Done means

• Feature available. The daemon supports Docker's experimental checkpoint feature.
• Target confirmed. The exact container and checkpoint name were confirmed with docker checkpoint ls.
• Clean exit. docker checkpoint rm returned status 0.
• Only the target went. A second listing shows the checkpoint gone and unrelated checkpoints intact.
• Nothing else touched. The container remains inspectable, and no storage directory was deleted by hand.