Search
English
Contents
  1. Docker tutorial
Getting started
  1. What is Docker
  2. Install Docker
  3. Docker Desktop interface tour
  4. Your first container
  5. Images
  6. Container lifecycle
  7. docker run flags
  8. View logs and debug
Images and Dockerfile
  1. Dockerfile basics
  2. Generate files with docker init
  3. Dockerfile instructions
  4. Build Cache and Optimization
  5. Multi-stage builds
  6. Push to Docker Hub
Data and networking
  1. Volumes and data persistence
  2. Networking and container communication
  3. Environment variables and .env
Docker Compose
  1. Docker Compose Tutorial
  2. compose.yaml syntax
  3. Docker Compose commands
  4. Build a WordPress Site
Real-world examples
  1. Python apps
  2. Node.js apps
  3. Nginx and reverse proxying
  4. MySQL
  5. PostgreSQL
  6. Redis
Operations and advanced topics
  1. Reclaim disk space
  2. Security best practices
  3. Rootless and Podman
  4. Multi-platform images
  5. Build automatically with GitHub Actions
  6. Deploy to a cloud server
  7. Internals
  8. Common error messages
  9. Docker command cheat sheet
Command reference
  1. docker build
  2. docker pull
  3. docker push
  4. docker rmi
  5. docker exec
  6. docker ps
  7. docker stop
  8. docker rm
  9. docker logs
  10. docker stats
  11. docker cp
  12. docker save
  13. docker inspect
  14. docker system
  15. docker volume
  16. docker network
  17. docker compose up
  18. docker compose down

Docker rmi tutorial: Remove images and tags with -f and image prune

docker rmi (alias docker image rm) removes image tags or unused images. If a container is using an image, you'll usually encounter a conflict. See Clean up disk space for ways to clean up images and disk space.

Syntax

docker rmi [OPTIONS] IMAGE [IMAGE...]
docker image rm [OPTIONS] IMAGE [IMAGE...]

Options

OptionDescription
-f, --forceForce removal of the image
--no-pruneDo not delete untagged parent images
--platform stringRemove only the specified platform variant, such as linux/amd64

Options for docker image prune:

OptionDescription
-a, --allRemove all unused images, not just dangling images
--filter FILTERProvide a filter, such as until=<timestamp>
-f, --forceDo not prompt for confirmation

Examples

The examples use the alpine, demo/app, redis, and registry images. Some tags point to the same image ID.

Remove a tag and encounter a conflict

$ docker images
IMAGE                                                                            ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:3.23                                                                      ff7f0c727dd7       26.6MB         8.21MB        
alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0   85fe1e81d675         13MB         3.94MB        
demo/app:1.0                                                                     ff7f0c727dd7       26.6MB         8.21MB        
demo/app:2.0                                                                     ff7f0c727dd7       26.6MB         8.21MB        
localhost:5000/tools/alpine:3.23                                                 ff7f0c727dd7       26.6MB         8.21MB        
localhost:5000/tools/alpine:latest                                               ff7f0c727dd7       26.6MB         8.21MB        
redis:8-alpine                                                                   0bf6577d7774        161MB         39.6MB   U    
registry:3                                                                       01cd312e6702       86.9MB         20.7MB   U    

$ docker rmi demo/app:1.0
Untagged: demo/app:1.0

$ docker rmi redis:8-alpine
Error response from daemon: conflict: unable to delete redis:8-alpine (must be forced) - container 0663b06bc225 is using its referenced image 0bf6577d7774
  • Removing demo/app:1.0 reports Untagged because the same image ID has other tags.
  • The redis:8-alpine image is being used by a container. Direct removal returns a conflict, and the error identifies the container ID and image ID.
  • The U in the EXTRA column indicates that the image is in use.

Force removal of a tag with -f

$ docker rmi -f redis:8-alpine
Untagged: redis:8-alpine

$ docker ps -a --filter name=uses-redis
CONTAINER ID   IMAGE          COMMAND                  CREATED         STATUS         PORTS      NAMES
0663b06bc225   0bf6577d7774   "docker-entrypoint.s…"   3 seconds ago   Up 3 seconds   6379/tcp   uses-redis

$ docker rmi nosuch:image
Error response from daemon: No such image: nosuch:image
  • -f successfully removes the redis:8-alpine tag. The container listed afterward is still running, showing that force-removing a tag does not stop the container.
  • Removing a nonexistent image name returns No such image.
  • After force removal, the image may remain locally with the <none> tag. Use docker system df -v to inspect detailed usage.

Prune dangling and all unused images

$ docker image prune -f
Total reclaimed space: 0B

$ docker image prune -a -f
Deleted Images:
untagged: alpine:3.23
untagged: alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
deleted: sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
deleted: sha256:1f3591b8a02ea153f41c5bba878ad477f63ab3d19349762cb77504db02a23e15
deleted: sha256:c3709935ef4cf35769588b317a43fa75b70a7ee51af2d449069ba66e956a0f44
untagged: localhost:5000/tools/alpine:3.23
untagged: localhost:5000/tools/alpine:latest
untagged: demo/app:2.0
deleted: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
deleted: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306
deleted: sha256:74a5b9d36e2dbe5329330986093322eb7619d9d5ebbc916392cf686d0e7381ce
deleted: sha256:8793abc479381bafd16c9d538b01c5a8dd7eef6aa10a737f2ad828ac73cb80e9
deleted: sha256:6d423cc7d2471ec6b5d77eaa820bc0808c1213c56c6fb88ccab237a486ecab64

Total reclaimed space: 26.7MB

$ docker images
IMAGE        ID             DISK USAGE   CONTENT SIZE   EXTRA
registry:3   01cd312e6702       86.9MB         20.7MB   U
  • Without -a, image prune removes only dangling images. This test had nothing to remove, so it reclaimed 0B.
  • With -a, it removes all images not used by containers, including images that still have tags. The registry:3 image remains because it is in use.
  • Docker 29 tends to leave fewer dangling images by default, so a regular image prune often reclaims no space. Use -a to remove all unused images.

Inspect <none> images and clean up with system prune

$ docker system df -v | head -20
Images space usage:

REPOSITORY   TAG           IMAGE ID       CREATED         SIZE      SHARED SIZE   UNIQUE SIZE   CONTAINERS
myweb        snapshot      56e3f92534ca   7 seconds ago   92.1MB    0B            92.08MB       0
nginx        1.30-alpine   47928bf67eb6   3 days ago      93.5MB    12.94MB       80.6MB        1
registry     3             01cd312e6702   3 days ago      86.9MB    12.94MB       73.93MB       1
<none>       <none>        0bf6577d7774   3 days ago      161MB     12.93MB       147.6MB       0
alpine       3.23          ff7f0c727dd7   3 days ago      13MB      12.93MB       86.86kB       1

Containers space usage:

CONTAINER ID   IMAGE               COMMAND                  LOCAL VOLUMES   SIZE      CREATED          STATUS          NAMES
0c009f73010b   alpine:3.23         "sleep 600"              0               4.1kB     42 seconds ago   Up 41 seconds   small
63b9a2f9c63f   nginx:1.30-alpine   "/docker-entrypoint.…"   0               115kB     44 seconds ago   Up 43 seconds   web
35357aad74b1   registry:3          "/entrypoint.sh /etc…"   1               20.5kB    2 minutes ago    Up 2 minutes    registry

Local Volumes space usage:

VOLUME NAME                                                        LINKS     SIZE
21ea99090ddead0461eb5a6efd670e1d9cf58fe9c23d5f8618db5868fb6170aa   1         3.854MB

$ docker system prune -f
Deleted Images:
untagged: sha256:0bf6577d7774e592b29d093e3ac9390eb91e13d72c21e506afce736de5e0eeb0
deleted: sha256:0bf6577d7774e592b29d093e3ac9390eb91e13d72c21e506afce736de5e0eeb0
deleted: sha256:16b124a2d3eacd620d917ead6fd26cbf1f1d7117fa94122398971931cfe2d403
deleted: sha256:f79a7876c6644b273e4eec899344e51c66959237a2f71188db8cb98d7311521c

Total reclaimed space: 147.6MB

$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          4         3         272.6MB   92.08MB (33%)
Containers      3         3         139.3kB   0B (0%)
Local Volumes   1         1         3.854MB   0B (0%)
Build Cache     0         0         0B        0B
  • docker system df -v shows the <none>:<none> image with ID 0bf6577d7774. No container is using it, but it still takes up 161MB, including 147.6MB of unique space.
  • docker system prune -f deletes this image and its related data, reclaiming 147.6MB. The Images usage then drops from 420.2MB to 272.6MB.
  • system prune cleans up other unused Docker data too. To handle only images, use docker image prune.

Exercises

Exercise: First try removing redis:8-alpine, then use -f to remove its tag, and confirm that the uses-redis container using that image is still running.

Answer 
docker rmi redis:8-alpine
docker rmi -f redis:8-alpine
docker ps -a --filter name=uses-redis

FAQ

Are docker rmi and docker image rm different commands?

No. docker rmi, docker image rm, and docker image remove are aliases for the same command.

Can you delete an image directly while a running container is using it?

A normal removal reports a conflict and identifies the container using the image. Adding -f removes the image tag; in our test, the container kept running.

What's the difference between docker image prune and docker image prune -a?

Without -a, it removes only dangling images; with -a, it removes all images not used by containers. In our Docker 29 test, the default prune reclaimed 0B, while -a deleted unused images.

Can you reclaim an image after using -f to remove an image used by a container?

docker system df -v shows the image retained with the <none> tag; in our test, docker system prune -f deleted it and reclaimed 147.6MB.

Updated October 26, 2026