The 'volume is in use' error occurs when Docker prevents you from removing a volume because a container (running or stopped) still references it. Stop and remove the dependent container first, or restart the Docker daemon if the reference is stale.
The "volume is in use" error in Docker appears when you try to delete a volume using `docker volume rm` while one or more containers still hold a reference to it. Docker uses reference counting to track which containers are attached to each volume. When you create a container with a volume mount (using `-v` or `--mount`), Docker increments this counter. Even after you stop a container, the reference persists until you explicitly remove the container with `docker rm`. This is a safety mechanism, not a bug. Docker prevents accidental data loss by ensuring you don't delete a volume that a container might still need. The error message typically includes the container ID in brackets to help you identify which container is blocking the removal. Importantly, the `--force` flag on `docker volume rm` does NOT override this protection - it only prevents errors when the volume doesn't exist. You must remove the container reference to delete the volume.
First, identify which containers are referencing the volume:
# List all containers (including stopped) using this volume
docker ps -a --filter volume=VOLUME_NAME
# Get just the container names for easier reading
docker ps -a --filter volume=VOLUME_NAME --format "{{.Names}}"
# Alternative: inspect the volume to see mount references
docker volume inspect VOLUME_NAMEReplace VOLUME_NAME with your actual volume name. The --filter volume= flag shows only containers that have this volume mounted.
Note: If docker ps returns nothing but docker ps -a shows containers, those are stopped containers that still hold the reference.
If any containers are still running, stop them first:
# Stop a specific container
docker stop <container_id_or_name>
# Stop all containers using the volume (one-liner)
docker stop $(docker ps -q --filter volume=VOLUME_NAME)Verify the containers are stopped:
docker ps --filter volume=VOLUME_NAMEThis should return an empty list if all containers using the volume are now stopped.
Stopping a container is not enough - you must remove it to release the volume reference:
# Remove a specific container
docker rm <container_id_or_name>
# Remove all containers using the volume
docker rm $(docker ps -a -q --filter volume=VOLUME_NAME)
# Or use container prune to remove all stopped containers
docker container pruneAfter removing the containers, try deleting the volume again:
docker volume rm VOLUME_NAMEIf the volume was created by Docker Compose, use the compose command to clean up properly:
# Navigate to your docker-compose.yml directory first
cd /path/to/your/project
# Stop and remove containers, networks (but not volumes)
docker compose down
# Stop and remove containers AND volumes
docker compose down --volumes
# or
docker compose down -vImportant: You must run this command from the directory containing your docker-compose.yml file, or specify the file with -f.
This is the cleanest way to remove Compose-managed volumes because it handles all the dependencies automatically.
In rare cases, Docker's internal reference counter may be out of sync due to a crash or race condition. Restarting the daemon resets this in-memory state:
# Linux (systemd)
sudo systemctl restart docker
# Linux (service)
sudo service docker restart
# macOS / Windows
# Restart Docker Desktop from the system tray/menu barAfter the daemon restarts, try removing the volume again:
docker volume rm VOLUME_NAMEIf this works, it confirms the issue was a stale reference rather than an actual container dependency.
If all else fails, you can manually remove the volume data. This is risky and should only be done when you're certain no containers need the data:
# Find the volume's physical location
docker volume inspect --format '{{ .Mountpoint }}' VOLUME_NAME
# Manually remove the volume directory (Linux only)
sudo rm -rf /var/lib/docker/volumes/VOLUME_NAME
# Restart Docker to refresh its volume list
sudo systemctl restart dockerWarning: This bypasses Docker's safety checks. Only use this when:
- You've verified no containers need this volume
- The volume contains no important data
- Other methods have failed
### Understanding Docker Volume Reference Counting
Docker tracks volume usage through reference counting in memory. Each time a container is created with a volume mount, the counter increments. When a container is removed (not just stopped), the counter decrements. A volume can only be deleted when its reference count reaches zero.
This is why the --force flag doesn't help - it's designed to prevent errors when the volume doesn't exist, not to override the reference count protection.
### Named vs Anonymous Volumes
Docker handles named and anonymous volumes differently:
| Type | Created By | Naming | Cleanup |
|------|-----------|--------|---------|
| Named | docker volume create or compose volumes: | User-specified | Manual only |
| Anonymous | -v /path without name | Random hash | Can use docker volume prune |
Anonymous volumes are easier to clean up with docker volume prune, but named volumes require explicit removal.
### Docker Desktop Extensions
If the volume belongs to a Docker Desktop extension, you may need to uninstall the extension through Docker Desktop's UI before the volume can be removed. Check Docker Desktop > Extensions to see installed extensions and their associated volumes.
### Cleaning Up Multiple Volumes
For bulk cleanup of unused volumes:
# Remove all unused volumes (those not referenced by any container)
docker volume prune
# Add -f to skip the confirmation prompt
docker volume prune -f
# Remove everything unused (containers, images, networks, volumes)
docker system prune --volumes### Volume Mounts in CI/CD
In CI/CD pipelines, stale volumes can accumulate. Consider adding cleanup to your pipeline:
# Start of pipeline - clean slate
docker compose down -v 2>/dev/null || true
docker volume prune -f
# ... run your pipeline ...
# End of pipeline - cleanup
docker compose down -v### Investigating Volume Contents
Before deleting a volume, you might want to inspect its contents:
# Create a temporary container to explore the volume
docker run -it --rm -v VOLUME_NAME:/data alpine sh
# Inside the container, explore /data
ls -la /dataThis lets you verify the volume is safe to delete or back up important data first.
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