How to fix WARN[0000] Found orphan containers ([container-name]) for this project. If you removed or renamed this service in your compose file, you can run this command with the --remove-orphans flag to clean it up. in Docker

DockerBEGINNERLOWUpdated Dec 1, 2025· 232 views

This warning appears when Docker Compose detects containers that belong to the same project but are no longer defined in your docker-compose.yml file. It typically happens after renaming or removing services, or when multiple compose files share the same project name.

Quick fix

Fixes WARN[0000] Found orphan containers ([container-name]) for this project. If you removed or renamed this service in your compose file, you can run this command with the --remove-orphans flag to clean it up.

# Remove orphans when starting services
docker-compose up -d --remove-orphans

# Or remove orphans when stopping services
docker-compose down --remove-orphans
  1. Remove orphan containers with the --remove-orphans flag
  2. Set a unique project name to avoid conflicts
  3. Suppress the warning if orphans are intentional
  4. Manually clean up orphan containers
docker — error
# Remove orphans when starting services
docker-compose up -d --remove-orphans
# Or remove orphans when stopping services
docker-compose down --remove-orphans
WARN[0000] Found orphan containers ([container-name]) for this project. If you removed or renamed this service in your compose file, you can run this command with the --remove-orphans flag to clean it up.

What this error means

When you run Docker Compose commands, it identifies containers using a project name, which by default is the name of the directory containing your `docker-compose.yml` file. This project name gets assigned to containers as the `com.docker.compose.project` label. The "Found orphan containers" warning appears when Docker Compose finds containers with a matching project label that aren't defined in the current `docker-compose.yml` file. This commonly happens in several scenarios: - **Removed services**: You deleted a service from your compose file, but its container still exists - **Renamed services**: You changed a service name, creating a new container while the old one remains - **Same directory name**: Two different projects happen to be in directories with the same name, causing their containers to share a project name - **Multiple compose files**: Running different compose files from the same directory without specifying unique project names This is a warning, not an error - your containers will still start normally. However, orphan containers consume resources and can cause confusion during debugging.

Typical symptoms

  • Warning message shows 'Found orphan containers' when running docker-compose commands
  • Message suggests using --remove-orphans flag
  • Containers from old/renamed services still appear in 'docker ps -a'
  • Multiple containers exist for what should be a single service
  • Warning appears after editing docker-compose.yml to remove or rename services

Common causes

  1. Service was removed from docker-compose.yml but its container still exists
  2. Service was renamed in docker-compose.yml, leaving the old container orphaned
  3. Multiple docker-compose files in the same directory have different service definitions
  4. Two different projects share the same directory name (default project name)
  5. Running docker-compose from a directory with an existing project name used elsewhere
  6. Switching between different docker-compose.yml files without cleaning up

How to fix "WARN[0000] Found orphan containers ([container-name]) for this project. If you removed or renamed this service in your compose file, you can run this command with the --remove-orphans flag to clean it up."

1Remove orphan containers with the --remove-orphans flag

The simplest solution is to let Docker Compose remove the orphan containers automatically:

bash
# Remove orphans when starting services
docker-compose up -d --remove-orphans

# Or remove orphans when stopping services
docker-compose down --remove-orphans

This tells Docker Compose to stop and remove any containers that belong to this project but aren't defined in the current compose file.

2Set a unique project name to avoid conflicts

If you have multiple projects or compose files that might conflict, give each a unique project name. There are three ways to do this:

Option 1: Use the -p flag

bash
docker-compose -p my-unique-project up -d

Option 2: Set COMPOSE_PROJECT_NAME in a .env file
Create a .env file in the same directory as your docker-compose.yml:

bash
COMPOSE_PROJECT_NAME=my-unique-project

Option 3: Add a top-level name in docker-compose.yml

yaml
name: my-unique-project

services:
  web:
    image: nginx
  # ... other services

This ensures different projects don't interfere with each other even if they're in directories with the same name.

3Suppress the warning if orphans are intentional

If the orphan containers are expected and you don't want to remove them, you can suppress the warning:

Set environment variable for a single command:

bash
COMPOSE_IGNORE_ORPHANS=true docker-compose up -d

Or add to your .env file for permanent effect:

bash
COMPOSE_IGNORE_ORPHANS=true

Use this option when you intentionally have containers from different compose files that you want to keep running.

4Manually clean up orphan containers

If you want to inspect and selectively remove orphan containers:

bash
# List all containers including stopped ones
docker ps -a

# Find containers belonging to the current project
docker ps -a --filter "label=com.docker.compose.project=$(basename $PWD)"

# Remove specific containers manually
docker rm -f <container_name_or_id>

This gives you more control if you only want to remove certain orphaned containers.

5Handle multiple compose files in the same directory

When working with multiple compose files (e.g., docker-compose.yml and docker-compose.test.yml), specify all files you want to use:

bash
# Explicitly use multiple compose files
docker-compose -f docker-compose.yml -f docker-compose.test.yml up -d

Or set the COMPOSE_FILE environment variable in your .env file:

bash
COMPOSE_FILE=docker-compose.yml:docker-compose.test.yml

This tells Docker Compose about all the services across both files, preventing false orphan warnings.

Advanced notes

Understanding project names: Docker Compose uses the project name as a namespace for all resources (containers, networks, volumes). The default project name is the directory name, converted to lowercase with special characters removed. You can verify the current project name with:

bash
docker-compose config | grep -i name

Why --remove-orphans doesn't work with some commands: Commands like docker-compose run and docker-compose create may suggest using --remove-orphans, but they don't actually accept this flag. In these cases, run docker-compose down --remove-orphans first, then execute your command.

Complete cleanup: For a thorough cleanup including volumes and images:

bash
docker-compose down --volumes --rmi all --remove-orphans

CI/CD considerations: In automated pipelines, always use explicit project names and --remove-orphans to ensure clean state:

bash
docker-compose -p ci-build-${BUILD_NUMBER} up -d --remove-orphans
# ... run tests ...
docker-compose -p ci-build-${BUILD_NUMBER} down --volumes --remove-orphans

Frequently asked questions

What does "WARN[0000] Found orphan containers ([container-name]) for this project" mean?
yml file. project label. yml file.
How do I fix "WARN[0000] Found orphan containers ([container-name]) for this project"?
This warning appears when Docker Compose detects containers that belong to the same project but are no longer defined in your docker-compose.yml file. It typically happens after renaming or removing services, or when multiple compose files share the same project name.
What causes "WARN[0000] Found orphan containers ([container-name]) for this project"?
Service was removed from docker-compose.yml but its container still exists Service was renamed in docker-compose.yml, leaving the old container orphaned Multiple docker-compose files in the same directory have different service definitions
Is the "WARN[0000] Found orphan containers ([container-name]) for this project" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading