Remove a Docker Image or Tag with docker image rm

You want one image gone, and docker image rm will happily take the wrong tag, or something a container still needs, if you let it. This guide removes a local image or tag under control: check what is affected, delete, then verify. Allow about ten minutes. The examples use Docker Community Edition CLI and engine 29.8.1, installed here as package docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble.

Warning: Image removal changes local state. Removing a tag is usually reversible by pulling or tagging again, but deleting locally stored layers can require a new pull. Do not use --force until you understand which tags, containers and platform variants refer to the image.

1. List the exact image reference

Start with a read-only inventory. The short form docker images is an alias for listing images, but the explicit command makes the object type clear:

$ docker image ls
IMAGE                                          ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:3                                      294b683cb724         13MB         3.94MB
alpine:latest                                 294b683cb724         13MB         3.94MB

Your list will differ. The two Alpine rows show why a tag and an image are not always the same thing: two tags can point at one image ID. Never select a row by position. Copy the complete repository and tag, a digest, or an image ID from your own output.

For a narrower check, inspect the reference you plan to use. Replace the value before running this command:

$ IMAGE_REF='REPLACE_WITH_AN_IMAGE_TAG_OR_ID'
$ docker image inspect "$IMAGE_REF" --format '{{.Id}} {{join .RepoTags ","}}'

Checkpoint: The inspection should print the image ID and its repository tags. If it says no such image exists, stop and correct the reference. Docker resolves an unqualified name such as alpine as the latest tag, so prefer an explicit tag when the distinction matters.

2. Understand what a normal removal does

Use docker image rm with one or more image references. It removes the reference from this host; it does not delete anything from a registry:

$ docker image rm REPLACE_WITH_THE_EXACT_IMAGE_REFERENCE

Replace the placeholder with a real value from the previous step. What you see depends on the tags:

Removing several references is one command, but check each one first:

$ docker image rm REPLACE_WITH_FIRST_REFERENCE REPLACE_WITH_SECOND_REFERENCE

Warning: Do not paste a shell wildcard in place of the references. Image removal accepts image arguments, not an approval prompt, so a broad generated list can remove more than you intended.

The command returns a non-zero status if one or more removals fail.

3. Save a recovery copy before deleting valuable content

If the image is expensive to rebuild or pull, save it first. This creates a tar archive and does not alter the image:

$ docker image save --output ./image-backup.tar REPLACE_WITH_THE_EXACT_IMAGE_REFERENCE
$ test -s ./image-backup.tar && echo 'backup archive is non-empty'

Keep the archive somewhere with enough free space and suitable access controls. It may contain application code, configuration or other sensitive material. To restore it later, use:

$ docker image load --input ./image-backup.tar

Tip: A registry pull is another recovery route, but it may give a different digest if the tag has moved. A saved archive preserves the local image content and tags it holds.

4. Handle tags, running containers and force carefully

If a tag points at an image with other tags, remove only the named tag first. This is the least disruptive choice. List all tags for the image ID before deciding whether the final tag should go:

$ docker image ls --no-trunc --format '{{.ID}} {{.Repository}}:{{.Tag}}' | sort

A running container can prevent removal of its image. The ordinary command should fail rather than silently force the change. Find containers that exist, including stopped ones, before considering an override:

$ docker container ls --all --filter ancestor=REPLACE_WITH_THE_EXACT_IMAGE_REFERENCE

If the container is disposable, remove it with the separate docker container rm command after checking its name and data mounts. If it is a service, stop it through its normal service manager or deployment tool. Do not delete a container merely to make an image removal succeed.

Warning: --force permits removal of an image that a running container uses. That is a destructive service decision, not a routine fix for a spelling error.

$ docker image rm --force REPLACE_WITH_THE_EXACT_IMAGE_REFERENCE

Check the container's restart policy and deployment definition first. Removing the image can leave a running container in place while preventing a restart or recreation until the image is pulled or loaded again.

5. Choose parent pruning deliberately

By default, Docker may remove untagged parent images made unnecessary by the operation. To keep those untagged parents for inspection or a later build, add --no-prune:

$ docker image rm --no-prune REPLACE_WITH_THE_EXACT_IMAGE_REFERENCE

This option does not preserve the tag you named. It only stops Docker pruning untagged parent content as part of that removal. Later cleanup commands, such as image pruning, can still remove unused content, so treat retained parents as temporary rather than as a backup.

Tip: --no-prune is not a dry run. The installed command has no dry-run option. Use docker image ls and docker image inspect as the review stage before the destructive command.

6. Remove one platform variant of a multi-platform image

Docker 29.8.1 supports --platform, using the os[/arch[/variant]] form such as linux/amd64. Without it, removal applies to all platform variants present for the reference. First inspect the image tree where the client supports that view:

$ docker image ls --tree REPLACE_WITH_THE_IMAGE_REFERENCE

Removing a specific platform variant affects any image references sharing that content, and it requires --force.

Warning: Treat this as a high-risk deletion and verify the platform spelling before you run it.

$ docker image rm --platform=linux/amd64 --force REPLACE_WITH_THE_IMAGE_REFERENCE

The platform flag can be repeated or supplied as a comma-separated list. The command's help output and the daemon API determine availability, so on an older remote daemon check docker version before relying on this option. The installed local client and engine report API 1.56.

7. Verify the removal and recover if needed

After a successful removal, inspect the reference again and check the command status immediately:

$ docker image inspect REPLACE_WITH_THE_EXACT_IMAGE_REFERENCE
$ printf 'inspect status: %s\n' "$?"

Checkpoint: A missing-image error and status 1 are expected when the reference no longer exists. If another tag still points at the same content, that tag keeps appearing in docker image ls. Verify the specific tag or platform you meant to remove, not just whether the image ID remains somewhere in the cache.

If you removed the wrong tag, restore it by pulling the intended registry reference or by adding a tag to an image that is still present:

$ docker image tag REPLACE_WITH_AN_EXISTING_IMAGE_ID REPLACE_WITH_THE_CORRECT_REPOSITORY_AND_TAG

Recovery: If the content was deleted, load the archive made in step 3 or pull the image again. If a service depended on the image, restore the deployment's normal image reference and restart it through the same controlled process you use for ordinary releases.

A successful docker image rm does not stop or remove a container, so do not assume it did.

Done means