The 'unable to delete image - image is being used by stopped container' error occurs when you try to remove a Docker image that still has one or more stopped containers associated with it. Remove the stopped containers first, or use the force flag to delete the image anyway.
The "unable to delete image (must be forced) - image is being used by stopped container" error means Docker is protecting you from deleting an image that a container still depends on. When you create a container from an image using `docker run` or `docker create`, Docker establishes a permanent reference between the container and its parent image. This reference persists even after the container stops. The container's writable layer sits on top of the image's read-only layers, and Docker needs that relationship intact so you can restart the container later. Docker's default behavior is to prevent image deletion when any container (running or stopped) depends on it. This safety measure ensures you don't accidentally break containers you might want to restart. The "(must be forced)" part of the message tells you that Docker will allow the deletion if you explicitly confirm it with the `-f` flag. This is not an error in the traditional sense - it's Docker working as designed to protect your containers and data.
The error message includes the container ID. You can also find all containers associated with an image:
# List ALL containers including stopped ones
docker ps -a
# Filter containers by the specific image
docker ps -a --filter ancestor=<image_name_or_id>
# Show container IDs, images, and status in a clear format
docker ps -a --format "table {{.ID}} {{.Image}} {{.Status}} {{.Names}}"Look for containers in "Exited" status - these are the stopped containers blocking the image deletion.
Once you've identified the container, remove it:
# Remove a specific container by ID or name
docker rm <container_id_or_name>
# Remove multiple containers
docker rm container1 container2
# Remove all containers associated with a specific image
docker rm $(docker ps -a --filter ancestor=<image_name> -q)After removing the container, retry deleting the image with docker rmi <image>.
If you have many stopped containers you no longer need:
# Remove all stopped containers
docker container prune
# You'll see a confirmation prompt - type 'y' to confirm
# WARNING! This will remove all stopped containers.
# Are you sure you want to continue? [y/N]This is a safe cleanup command that only removes stopped containers, not running ones.
If you want to delete the image without first removing containers, use the force flag:
# Force remove by image name
docker rmi -f <image_name>
# Force remove by image ID
docker rmi -f <image_id>Warning: Force-removing an image will:
- Delete the image even though containers depend on it
- Leave those containers unable to restart
- Not remove the containers themselves (they become orphaned)
Use this when you're certain you don't need the dependent containers.
Confirm the image is gone:
# List all images
docker images
# Search for the specific image
docker images | grep <image_name>
# Or use filter
docker images --filter reference=<image_name>If the image no longer appears, the deletion was successful.
### Understanding Container-Image Dependencies
Docker uses a layered filesystem (UnionFS). When you run a container:
1. The image provides read-only base layers
2. Docker adds a thin writable layer on top for the container
3. This writable layer records all changes made during the container's lifetime
Even when stopped, the container's writable layer maintains a reference to the base image. Deleting the image would corrupt this relationship.
### Automating Cleanup in CI/CD
For CI/CD pipelines, always clean up containers after tests:
#!/bin/bash
# Run container for tests
docker run --name test-container myimage:latest ./run-tests.sh
# Always remove container, even if tests fail
docker rm -f test-container 2>/dev/null || true
# Or use --rm flag to auto-remove on exit
docker run --rm myimage:latest ./run-tests.sh### The --rm Flag
Prevent this error entirely by using the --rm flag when running containers:
# Container automatically removed when it stops
docker run --rm myimage:latest echo "Hello"This is ideal for one-off commands, builds, and tests where you don't need the container afterwards.
### Docker Compose Cleanup
If containers were created via Docker Compose:
# Stop and remove all containers, networks
docker compose down
# Also remove images built by compose
docker compose down --rmi all
# Also remove volumes (careful - this deletes data!)
docker compose down -v### System-Wide Cleanup
For a complete cleanup of unused Docker resources:
# Remove stopped containers, unused networks, dangling images
docker system prune
# Also remove all unused images (not just dangling)
docker system prune -a
# Include unused volumes (WARNING: deletes volume data)
docker system prune -a --volumes### Inspecting Container Details
To understand why a container exists:
# See full container details
docker inspect <container_id>
# Check when container was created and what image it uses
docker inspect --format '{{.Created}} - {{.Image}}' <container_id>
# See the command that was run
docker inspect --format '{{.Config.Cmd}}' <container_id>dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec