The 'remove volume: volume is in use' error occurs when you try to delete a Docker volume that is still referenced by a container. Remove or stop the dependent container first, then delete the volume.
The "remove volume: volume is in use" error appears when you attempt to delete a Docker volume using `docker volume rm` while a container still holds a reference to it. Docker maintains an internal reference count for each volume. When you create a container with a volume mount (via `-v`, `--mount`, or Docker Compose), Docker increments this counter. Even after stopping a container, the reference persists until the container is explicitly removed with `docker rm`. This is a safety feature, not a bug. Docker prevents accidental deletion of volumes that containers might still need. The error message typically includes the container ID to help you identify which container is blocking the removal. Note that the `--force` flag on `docker volume rm` does not override this protection. It only suppresses errors when the volume doesn't exist. You must first remove the container to release the volume reference.
First, identify which containers are referencing the volume:
# List all containers (including stopped) using this volume
docker ps -a --filter volume=VOLUME_NAME
# Get container names only
docker ps -a --filter volume=VOLUME_NAME --format "{{.Names}}"
# Inspect the volume for 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.
Tip: If docker ps returns nothing but docker ps -a shows containers, those are stopped containers still holding the reference.
If containers are still running, stop them first:
# Stop a specific container
docker stop <container_id_or_name>
# Stop all containers using the volume
docker stop $(docker ps -q --filter volume=VOLUME_NAME)Verify containers are stopped:
docker ps --filter volume=VOLUME_NAMEThis should return an empty list.
Stopping is not enough - remove the containers 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 prune all stopped containers
docker container pruneNow try deleting the volume again:
docker volume rm VOLUME_NAMEIf the volume was created by Docker Compose, use the compose commands:
# Navigate to your docker-compose.yml directory
cd /path/to/your/project
# Stop and remove containers (keeps volumes)
docker compose down
# Stop and remove containers AND volumes
docker compose down --volumes
# or the shorthand
docker compose down -vImportant: Run this from the directory containing your docker-compose.yml or specify the file with -f.
This is the cleanest way to remove Compose-managed volumes.
In rare cases, Docker's reference counter may be out of sync. Restart the daemon:
# Linux (systemd)
sudo systemctl restart docker
# Linux (service)
sudo service docker restart
# macOS / Windows
# Restart Docker Desktop from the system tray/menu barAfter restart, try removing the volume:
docker volume rm VOLUME_NAMEIf all else fails, manually remove the volume 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 the volume list
sudo systemctl restart dockerWarning: This bypasses Docker's safety checks. Only use when:
- No containers need this volume
- The volume contains no important data
- All other methods have failed
### How Docker Volume Reference Counting Works
Docker tracks volume usage through in-memory reference counting. Each container creation with a volume mount increments the counter. Container removal (not just stopping) decrements it. A volume can only be deleted when the count reaches zero.
The --force flag on docker volume rm doesn't override this - it's designed to suppress "volume not found" errors, not bypass reference protection.
### Named vs Anonymous Volumes
| Type | Created By | Naming | Cleanup Method |
|------|-----------|--------|----------------|
| Named | docker volume create or compose volumes: | User-specified | Manual docker volume rm |
| Anonymous | -v /path without name | Random hash | docker volume prune |
Anonymous volumes can be cleaned with docker volume prune, but named volumes require explicit removal.
### Bulk Volume Cleanup
For removing multiple unused volumes:
# Remove all unused volumes
docker volume prune
# Skip confirmation prompt
docker volume prune -f
# Nuclear option: remove everything unused
docker system prune --volumes### CI/CD Pipeline Considerations
Stale volumes can accumulate in CI environments. Add cleanup to your pipeline:
# Start of pipeline
docker compose down -v 2>/dev/null || true
docker volume prune -f
# ... pipeline steps ...
# End of pipeline
docker compose down -v### Inspecting Volume Contents Before Deletion
Check volume contents before deleting:
# Create a temporary container to explore
docker run -it --rm -v VOLUME_NAME:/data alpine sh
# Inside the container
ls -la /datadockerfile 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