docker-rmi

Display help

$ docker rmi

$ docker rmi [image1 image2 ...]

$ docker rmi [[-f|--force]] [image]

$ docker rmi --no-prune [image]

docker rmi [OPTIONS] IMAGE [IMAGE...]

-f, --force
    
Forces the removal of an image. This option can bypass checks, allowing the deletion of images even if they are used by stopped containers or are parents of other images. Use with caution as it can lead to orphaned containers or broken image dependencies.

--no-prune
    
Prevents the deletion of untagged parent images. By default, `docker rmi` will remove untagged parent images (dangling images) if they are no longer referenced by any other image after the specified image is removed. This option disables that automatic pruning behavior.

IMAGE [IMAGE...]
    
One or more image names, IDs, or digests to be removed. You can specify multiple images by listing them space-separated.

The `docker rmi` command (short for remove image) is a fundamental part of the Docker CLI, used to delete one or more Docker images from the local image store. It's essential for managing disk space and keeping your Docker environment clean by removing old, unused, or unwanted image layers.

Images can be specified by their ID, name (e.g., `ubuntu:latest`), or digest. By default, `docker rmi` will prevent the removal of an image if it's currently referenced by a running container, or if it's a parent of another existing tagged image. This default behavior helps prevent accidental data loss or breaking dependencies.

For more aggressive cleanup, especially when an image is referenced by stopped containers or when dealing with complex image dependencies, options like `--force` can be used. It's crucial to understand the implications of removing images, as it can affect existing containers or break subsequent image builds if dependencies are not carefully managed.

An image cannot be removed if a container is currently running from it. You must stop and remove the container first (using `docker stop` and `docker rm`).

If an image is referenced by a stopped container, you will need to use the `--force` option to remove it. Be aware that this will leave the stopped container referencing a non-existent image.

Images that are parents of other tagged images cannot be removed unless the child images are removed first, or the `--force` option is used. Using `--force` in such cases can lead to child images that lack their foundational layers, potentially causing issues.

Be cautious with `--force` as it can lead to unexpected behavior, orphaned resources, or corrupted Docker environments if not used judiciously. Always ensure you understand the dependencies before forcing image removal.

The term "docker-rmi" is a common way users might conceptually refer to the command. However, in the Docker CLI, subcommands are always separated from the main `docker` command by a space, not a hyphen. Therefore, the correct and executable command is `docker rmi`. The hyphenated form is a common typo or a conceptual carry-over from other command-line interfaces where hyphens are used to separate commands (e.g., `git-add` sometimes refers to `git add`).

Dangling images are image layers that have no relationship to any tagged images. They often occur when you build a new image and the previous layers become untagged but are still present on your system. While `docker rmi` can remove specific dangling images if you know their IDs, `docker image prune` is the more efficient and recommended command to clean up all dangling images or even all unreferenced images (those not used by any container and not having any tags).

The `docker rmi` command has been a core component of the Docker CLI since its early versions, reflecting the fundamental need for users to manage their local image cache. Its functionality has remained largely consistent over time, emphasizing its role in cleaning up disk space and maintaining image hygiene.

As Docker matured, more sophisticated image management tools like `docker image prune` were introduced (starting with Docker 1.13, part of the new `docker image` subcommand structure) to complement `rmi` for automated and comprehensive cleanup of unused images, including dangling and unreferenced ones. While `docker rmi` is for explicit image removal, `docker image prune` offers a more automated approach to reclaim disk space.

docker images(1), docker image prune(1), docker pull(1), docker build(1), docker run(1), docker rm(1)