Remove a Local Manifest List with docker manifest rm

A stale manifest list is sitting in your Docker CLI store, and docker manifest rm clears it out without touching the registry. You will remove one or more local lists while leaving registry content and ordinary image tags alone. This guide uses the installed Docker Community CLI 29.8.1, from package docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble.

Allow about ten minutes. You need a shell, permission to read the Docker CLI configuration directory, and the exact manifest-list references you intend to remove. The normal command does not need sudo.

Destructive action: This is local metadata cleanup, but once a local list is removed you must recreate it from its source images or use a previously pushed copy.

1. Check the installed command

Confirm the binary and package before relying on examples. These are ordinary, read-only checks:

$ command -v docker
/usr/bin/docker
$ docker version --format '{{.Client.Version}}'
29.8.1
$ dpkg-query -W -f='${Package} ${Version}\n' docker-ce-cli
docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble

The local manual gives this command shape:

$ docker manifest rm MANIFEST_LIST [MANIFEST_LIST...]

Each argument is a manifest-list reference, normally an image name with a tag such as registry.example.test/team/app:release. The command accepts one or more references in the same invocation. It has no removal option, force flag or confirmation prompt.

Checkpoint: The version and command path are the ones you expected. If not, stop and check your Docker context and package installation before removing anything.

2. Identify the exact local list

A manifest list is local data created for Docker's manifest workflow. It describes images for multiple platforms and can be pushed to a registry later. The reference is not a container name, volume name or ordinary image ID. Write down the complete name and tag, including the registry hostname when one is present.

Inspect a candidate without changing it:

$ docker manifest inspect registry.example.test/team/app:release
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json"
  ...
}

The full response depends on the registry and manifest. The useful check is that you are looking at the intended reference and that it describes a manifest list or index. An inspect request can contact the registry, so it may fail when the registry is private, unavailable or requires credentials. That failure does not identify a safe local deletion target.

Do not derive the name from a shortened display label.
Do not remove a tag just because it shares a repository name with a local list. The command operates on the manifest-list reference held by Docker's local manifest store.

3. Know what removal touches

docker manifest rm deletes local manifest-list data. It does not remove a manifest list from a registry, and it does not delete the child images named by that list. It also does not remove containers, volumes or ordinary image layers.

Warning: A later local command that needs the list may no longer find it. If the list was not pushed, there may be no remote copy to recover. Record the source image references and any platform annotations you would need to recreate it.

For an existing list, capture a record first if you may need to rebuild it:

$ docker manifest inspect registry.example.test/team/app:release > app-release-manifest.json
$ test -s app-release-manifest.json && echo "manifest record saved"
manifest record saved

This writes a copy of the inspect response in the current directory. Choose a protected working directory if the response contains private registry details. Do not commit credentials or registry responses to a public repository.

4. Remove one local manifest list

Replace the placeholder with the exact reference you checked. This is normally an unprivileged command:

$ docker manifest rm registry.example.test/team/app:release
registry.example.test/team/app:release

A successful command exits with status 0 and reports the removed reference. The output confirms the local cleanup. It is not proof that a registry object was changed. If your shell needs an explicit status check:

$ printf 'exit status: %s\n' "$?"
exit status: 0

Tip: Do not add sudo automatically. The Docker CLI reads the current user's Docker configuration and local manifest data. Running as root changes which user's Docker files are used and can make the result confusing. Use elevated privileges only if your system's Docker installation or file permissions genuinely require them, and verify the target again in that context.

5. Remove several lists only after checking each name

Several references can be supplied in one command. Treat this as one destructive batch: review every argument before pressing Return.

$ docker manifest rm \
    registry.example.test/team/app:release \
    registry.example.test/team/app:staging
registry.example.test/team/app:release
registry.example.test/team/app:staging

Warning: There is no wildcard syntax in the documented usage. Do not generate a list from an unreviewed directory glob or from text copied out of logs. If you have many names, put the reviewed references in a plain file and inspect the resulting command before running it. Keep each reference shell-quoted if it comes from a variable or external input.

When a supplied reference does not exist locally, the command reports an error such as No such manifest: ... and returns a non-zero status. A failed lookup is a reason to check the spelling and Docker configuration, not a reason to retry with a different, guessed tag.

6. Recover by recreating the list

There is no undo flag for docker manifest rm. Recovery means recreating the manifest list from the child image references, or obtaining it again from a registry where it was pushed. The exact create command depends on those source images and your registry credentials, so do not invent replacements from the removed tag alone.

If you have verified source references, the Docker manifest workflow can create a new local list:

$ docker manifest create registry.example.test/team/app:release \
    registry.example.test/team/app:release-amd64 \
    registry.example.test/team/app:release-arm64
Created manifest list registry.example.test/team/app:release

Use only child images that exist and represent the platforms you intend to publish. After creation, inspect the list again:

$ docker manifest inspect registry.example.test/team/app:release
{
  "schemaVersion": 2,
  "manifests": [
    ...
  ]
}

Warning: If the list is meant to be shared, pushing it is a separate operation and can affect a registry. Review the repository policy and credentials before using docker manifest push. Removing the local copy does not undo a previous push.

7. Keep the experimental status in mind

The installed help marks docker manifest rm as experimental. Docker documents experimental features as subject to change or removal without the compatibility guarantees you might expect from a stable command. Pin and test the Docker CLI version in automation, and keep a copy of the manifest inspection result when a rebuild would be costly.

For a script, fail closed around the destructive call:

Use explicit references.
Check the exit status.
Log which references were approved.

Do not treat a successful exit as proof that a remote registry was altered. The command's scope is local storage.

Done means

Reference confirmed. You checked the Docker CLI version and the exact manifest-list reference.
Record kept. You inspected or saved the list before deletion when recovery might matter.
Batch reviewed. You checked every argument in a multi-list removal command.
Local only. You removed manifest-list data, and did not confuse it with registry, image, container or volume removal.
Exit status checked. You know a missing list returns a non-zero result.
Rebuild path ready. You have the child image references or a pushed copy if the list must be recreated.