The 5-Second Fix
Want to make that warning disappear instantly? Just append the --remove-orphans flag when you bring your stack up. This tells Docker to wipe any containers that are no longer defined in your YAML file.
docker compose up -d --remove-orphans
If you prefer to tidy up without starting new services, run the down command with the same flag:
docker compose down --remove-orphans
Why is Docker complaining?
Docker Compose keeps track of every container it creates using a "project name." This warning triggers when Docker finds a container belonging to your project that is no longer mentioned in your docker-compose.yml. Even an idle Alpine-based container can hog 5MB to 10MB of RAM, while a forgotten database could sit on 200MB+ of memory for no reason.
Most developers run into this in three specific scenarios:
- Renaming a service: You changed
db:topostgres-db:. The olddbcontainer is now a "ghost" in your system. - Pruning your stack: You deleted a service like
redisormailhogbecause you moved to a managed service or a different tool. - Switching Git branches: You moved from a feature branch with a complex 6-service architecture back to
main, which only uses 2 services. Those 4 extra containers are now orphans.
Three Ways to Resolve the Issue
Method 1: The Standard Flag (Best for Daily Use)
Usually, you just want these containers gone. They clutter your docker ps output and can occasionally hold onto ports like 8080 or 5432, preventing new services from starting. Adding the flag to your up command is the most efficient workflow.
# Clean up and start in one go
docker compose up -d --remove-orphans
Under the hood, Docker identifies the IDs of the rogue containers and executes a docker rm -f on them before proceeding with your current configuration.
Method 2: Investigating Before Deleting
Don't kill the container immediately if you think it might hold unsaved data. If the warning mentions Found orphan containers (legacy_api_service), take a peek inside first.
# Check if the orphan is still running
docker ps -a --filter "name=legacy_api_service"
# Inspect logs to see if it was doing something important
docker logs legacy_api_service
# Remove it manually once you're sure
docker rm -f legacy_api_service
This manual approach is a lifesaver if you accidentally deleted a service definition but forgot to back up a database stored in the container's ephemeral layer.
Method 3: Fixing Project Name Collisions
By default, Docker uses your folder name as the project name. If you have two different projects in folders both named /app, Docker will confuse their containers. It might try to "clean up" containers from the wrong project entirely.
Fix this by setting a unique project name in your .env file:
# .env file
COMPOSE_PROJECT_NAME=ecommerce_v2_staging
Alternatively, use the -p flag in your CLI commands to keep things isolated:
docker compose -p unique_project_name up -d --remove-orphans
Confirming the Cleanup
Check your environment after running the fix. A quick docker compose ps should show a clean list. The output should now match your docker-compose.yml exactly. If you run up again, that annoying yellow warning text should be gone.
Pro Tip: Use an Alias
If you're tired of typing the extra characters, add an alias to your .zshrc or .bashrc. I use this to keep my workspace clean by default:
alias dcup='docker compose up -d --remove-orphans'
A Note on Hidden Data
Removing a container doesn't automatically delete its volumes. If your orphan service had a named volume for persistent storage, that data is still taking up space on your NVMe or SSD. To see how much space you're losing to dangling volumes, run:
docker system df
If you want to wipe those unattached volumes, use docker volume prune. Just be careful—this command is destructive and will remove any volume not currently connected to an active container.