How to fix Error response from daemon: conflict: unable to remove repository reference (must force) in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 254 views

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.

Quick fix

Fixes Error response from daemon: conflict: unable to remove repository reference (must force)

# 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}}"
  1. List all containers using the image
  2. Stop running containers using the image
  3. Remove the dependent containers
  4. Force remove the image (if needed)
docker — error
# 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}}"
Error response from daemon: conflict: unable to remove repository reference (must force)

What this error means

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.

Typical symptoms

  • Running `docker rmi <image>` returns 'unable to remove repository reference'
  • Error message includes '(must force)' at the end
  • The same image can be pulled but not deleted
  • Multiple attempts to delete the image fail with the same error
  • Docker Desktop shows the image but won't let you delete it through the UI
  • `docker images` shows the image, but `docker ps` shows no running containers

Common causes

  1. A stopped container is still using the image (most common)
  2. A running container is using the image
  3. Multiple containers (running or stopped) depend on the image
  4. The image is tagged with multiple repository references
  5. A child image was built from this image (image layers dependency)
  6. Docker Compose created containers that weren't properly cleaned up

How to fix "Error response from daemon: conflict: unable to remove repository reference (must force)"

1List all containers using the image

First, find all containers (including stopped ones) that depend on this image:

bash
# 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.

2Stop running containers using the image

If any containers using the image are still running, stop them first:

bash
# 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.

3Remove the dependent containers

Now remove the stopped containers that were using the image:

bash
# 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>.

4Force remove the image (if needed)

If you want to delete the image regardless of dependent containers, use the force flag:

bash
# 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 image3

Warning: 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.

5Handle images with multiple tags

If an image has multiple repository tags, you need to remove each tag or untag first:

bash
# 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:latest

When an image has multiple tags, removing one tag just untags it. The image is only deleted when the last tag is removed.

6Clean up all unused images and containers

For a thorough cleanup of unused Docker resources:

bash
# 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 --volumes

Note: docker system prune -a will remove ALL images not used by at least one container. Be careful in production environments.

Advanced notes

### 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:

bash
# 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:

bash
# 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:

bash
#!/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_REMOVE

Frequently asked questions

What does "Error response from daemon: conflict: unable to remove repository refe" mean?
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.
How do I fix "Error response from daemon: conflict: unable to remove repository refe"?
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.
What causes "Error response from daemon: conflict: unable to remove repository refe"?
A stopped container is still using the image (most common) A running container is using the image Multiple containers (running or stopped) depend on the image
Is the "Error response from daemon: conflict: unable to remove repository refe" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading