The 'unable to remove repository reference (must force)' error occurs when Docker cannot delete an image because a container (running or stopped) is still using it. Remove dependent containers first, or use the force flag to delete the image.
The "unable to remove repository reference (must force)" error in Docker happens when you try to delete an image that has one or more containers attached to it. When you create a container from an image using `docker run` or `docker create`, Docker maintains a reference between the container and its parent image. Even after a container stops, this relationship persists until the container is explicitly removed with `docker rm`. Docker prevents image deletion by default to protect you from accidentally removing an image that a container depends on. If you deleted the image, the stopped container's filesystem would become invalid and you couldn't restart it. This is a safety mechanism, not a bug. The error message "(must force)" indicates that Docker will allow the deletion if you really want it, but you must explicitly use the `-f` flag to confirm your intention.
First, find all containers (including stopped ones) that depend on this image:
# List ALL containers (including stopped ones)
docker ps -a
# Filter to find containers using a specific image
docker ps -a --filter ancestor=<image_name>
# Or use format to see container IDs and images clearly
docker ps -a --format "table {{.ID}} {{.Image}} {{.Status}} {{.Names}}"The --filter ancestor=<image> flag shows only containers created from that image. Note that stopped containers appear in docker ps -a but not in docker ps.
If any containers using the image are still running, stop them first:
# Stop a specific container
docker stop <container_id_or_name>
# Stop multiple containers
docker stop container1 container2 container3
# Stop all running containers (use with caution)
docker stop $(docker ps -q)You can verify the container is stopped by running docker ps - it should no longer appear in the list.
Now remove the stopped containers that were using the image:
# Remove a specific container
docker rm <container_id_or_name>
# Remove multiple containers
docker rm container1 container2 container3
# Remove all stopped containers
docker container prune
# Or remove specific containers by image
docker rm $(docker ps -a --filter ancestor=<image_name> -q)After removing the containers, try deleting the image again with docker rmi <image>.
If you want to delete the image regardless of dependent 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>
# Remove multiple images
docker rmi -f image1 image2 image3Warning: Force-removing an image will:
- Remove the image even if containers depend on it
- Leave dependent containers in a broken state (they won't be able to restart)
- Not delete the containers themselves
Use this only when you're sure you don't need those containers.
If an image has multiple repository tags, you need to remove each tag or untag first:
# List all tags for an image
docker images | grep <image_id_prefix>
# Remove by specific tag
docker rmi myregistry/myimage:v1
docker rmi myregistry/myimage:latest
# Or untag without deleting
docker rmi myregistry/myimage:v1 # Removes tag only if other tags exist
# Then remove the final reference
docker rmi myimage:latestWhen an image has multiple tags, removing one tag just untags it. The image is only deleted when the last tag is removed.
For a thorough cleanup of unused Docker resources:
# Remove all stopped containers
docker container prune
# Remove all unused images (not just dangling ones)
docker image prune -a
# Remove everything unused (containers, images, networks, build cache)
docker system prune -a
# Add --volumes to also remove unused volumes (careful with data!)
docker system prune -a --volumesNote: docker system prune -a will remove ALL images not used by at least one container. Be careful in production environments.
### Understanding Docker Image Layers
Docker images are built from layers. When you run docker build, each instruction (FROM, RUN, COPY, etc.) creates a new layer. Parent images share layers with child images, which is why you might not be able to delete a base image if derived images exist.
To see image dependencies:
# List all images including intermediate layers
docker images -a
# Inspect image layers
docker history <image_name>### Why Docker Protects Images
Docker maintains referential integrity between containers and images for good reasons:
1. Restart capability: A stopped container can be restarted with docker start. This requires the parent image.
2. Filesystem consistency: The container's filesystem is built on top of the image's read-only layers.
3. Data preservation: Some containers store important data that would be lost if accidentally deleted.
### Docker Compose Cleanup
If containers were created by Docker Compose, use compose commands for cleanup:
# Stop and remove containers created by compose
docker compose down
# Also remove volumes
docker compose down -v
# Also remove images
docker compose down --rmi all### Container States Reference
Understanding container states helps diagnose this error:
| State | docker ps | docker ps -a | Can restart? |
|-------|-------------|-----------------|--------------|
| Running | Yes | Yes | N/A (already running) |
| Stopped | No | Yes | Yes |
| Removed | No | No | No |
A container must be removed (not just stopped) before its parent image can be deleted without force.
### Scripting Image Cleanup
For automated cleanup in CI/CD pipelines:
#!/bin/bash
# Safe image cleanup script
IMAGE_TO_REMOVE="myimage:latest"
# Find and remove all containers using this image
CONTAINERS=$(docker ps -a --filter ancestor=$IMAGE_TO_REMOVE -q)
if [ -n "$CONTAINERS" ]; then
echo "Removing containers: $CONTAINERS"
docker rm -f $CONTAINERS
fi
# Now remove the image
docker rmi $IMAGE_TO_REMOVEdockerfile 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