Docker Compose Prune: How to Clean Up Orphaned Containers
Docker compose prune is the easiest way to remove orphaned containers. Learn how to identify stale resources and keep your local Docker environment clean.
I spent about two hours last week trying to figure out why my local API was hitting a database version I’d deleted from my docker-compose.yml file three days ago. It turned out I had a handful of "orphaned" containers lingering in the background, holding onto network ports and stale volumes.
If you’ve been working with containers for a while, you know the drill: you rename a service, change a base image, or remove a project entirely, but the old containers stay put. They don't just consume disk space; they can cause silent, infuriating configuration drift.
Why Orphaned Containers Happen
Docker Compose is designed to manage the lifecycle of the services defined in your current configuration. When you run docker-compose up, it starts what it sees in the file. However, if you rename a service or delete it from the YAML without running docker-compose down, Compose loses track of that resource. It becomes an "orphan"—a container that exists on your host but is no longer part of your project’s definition.
I used to think that just running docker-compose down would fix everything. While it works for the current project, it doesn't do anything for orphaned containers created by older versions of your configuration or abandoned side-projects.
Finding Your Orphans
Before you start deleting, you need to see what’s actually running. If you want to check for containers that aren't tied to your current Compose project, use the --remove-orphans flag.
Bashdocker-compose up -d --remove-orphans
This command is a lifesaver. It tells Compose to compare the running containers with the services defined in your YAML and kill anything that doesn't belong. If you just want to list them without taking action, you're better off using docker ps with a filter. I usually run this to see what's clogging up my machine:
Bashdocker ps -a --filter "status=exited"
Using Docker Compose Prune
When you need a clean slate, docker compose prune isn't actually a single command, but rather a set of tools you use to perform a docker compose cleanup. Docker provides a powerful prune command that targets specific resources.
To wipe out stopped containers, unused networks, and dangling images in one go, use:
Bashdocker system prune
Be careful with this. It’s aggressive. If you have containers you’re keeping for inspection, they will be gone. If you want to be more surgical about your docker orphaned containers management, target the specific resource types:
- Containers:
docker container prune - Volumes:
docker volume prune - Networks:
docker network prune
Managing Persistent Data
The trickiest part of docker volume management is that volumes often persist even after you remove the containers that used them. If you’ve spent time debugging Docker Compose Networking: How to Fix Service Connectivity Issues, you know that stale volumes can harbor old configuration files or corrupted database states.
I recommend running docker volume ls periodically. If you see volumes with names like myapp_db_data that you haven't touched in weeks, they are prime candidates for deletion.
| Resource Type | Cleanup Command | Impact |
|---|---|---|
| Containers | docker container prune | Removes all stopped containers |
| Volumes | docker volume prune | Removes all unused local volumes |
| Networks | docker network prune | Removes unused bridge networks |
| Everything | docker system prune -a | Wipes stopped containers, networks, and images |
Best Practices for a Clean Workflow
I’ve found that the best way to avoid this mess is to build cleanup into my routine. If you're dealing with complex build environments, make sure to check your Docker build cache debugging: Fix slow incremental builds to ensure you aren't storing massive, unnecessary layers that contribute to the "clutter" feeling.
If you find yourself doing this daily, you might want to automate it. I’ve previously written about Docker Pruning Automation: Managing Orphaned Resources with Systemd if you want to let the OS handle the heavy lifting for you.
FAQ
Q: Does docker-compose down remove volumes?
A: No, by default it doesn't. You need to run docker-compose down -v to remove named volumes defined in your Compose file.
Q: Will docker system prune delete my database data?
A: It will delete any volumes that are not currently attached to a running container. If your database container is stopped, the volume might be pruned. Always back up critical data before running global prune commands.
Q: How do I stop orphaned containers from being created?
A: Always use the --remove-orphans flag when starting your stack. It’s the single most effective way to keep your environment synced with your YAML file.
I’m still not perfect at this. I occasionally find a 5GB volume from a project I deleted months ago. The key is to treat your Docker environment like a garden—you have to weed it occasionally, or it’ll eventually choke your disk space.