Fix 'Found orphan containers' in docker compose up

What the error means

Docker Compose shows "Found orphan containers" when containers from the same project name exist that are not defined in your current compose files. This usually happens after you:

• Remove or rename a service
• Switch compose files or paths
• Change the project name (-p or COMPOSE_PROJECT_NAME)

These leftover containers keep running but are unmanaged by your current configuration.

Quickstart (most common fix)

• One-time cleanup during up:
  • docker compose up -d --remove-orphans
• Full reset of the current project:
  • docker compose down --remove-orphans && docker compose up -d

If you only want to silence the message (not recommended):

• COMPOSE_IGNORE_ORPHANS=1 docker compose up -d

Minimal working example

This shows how orphans appear and how to fix them.

1. Start a simple app

a version: '3.9'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: example

# Start both services
docker compose up -d

1. Remove the db service from the file and re-run

a version: '3.9'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

# Recreate project with the new file
docker compose up -d
# You will see: Found orphan containers (yourproject-db-1)

1. Fix

docker compose up -d --remove-orphans
# or
docker compose down --remove-orphans && docker compose up -d

Step-by-step diagnosis

1. Confirm your current project name

# Shows compose projects and their status
docker compose ls

If you prefer explicit naming, set a project name and keep it consistent:

export COMPOSE_PROJECT_NAME=myapp
# or pass per command
docker compose -p myapp up -d

1. List services defined in your current files

docker compose config --services

1. List running containers for the project and spot strays

# Replace PROJECT with the name from step 1
PROJECT=$(basename "$PWD")  # default project name is directory name
# If you used -p or COMPOSE_PROJECT_NAME, set PROJECT accordingly

docker ps --filter "label=com.docker.compose.project=$PROJECT" --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

Any container with the project label that is not in config --services is an orphan.

1. Inspect a container’s project label (optional)

# Prints the compose project label of a container
docker inspect -f '{{index .Config.Labels "com.docker.compose.project"}}' <container>

Reliable fixes and when to use them

• Remove strays without downtime for current services
  • docker compose up -d --remove-orphans
• Clean slate for the project (stops everything, keeps volumes)
  • docker compose down --remove-orphans
• Clean slate and also remove named/anonymous volumes (data loss!)
  • docker compose down -v --remove-orphans
• You changed files with -f; use the same set consistently
  • docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --remove-orphans
• You changed the project name; align it
  • docker compose -p myapp up -d --remove-orphans

Common scenarios and commands

Preventing reoccurrence

• Keep project naming consistent
  • Use a fixed COMPOSE_PROJECT_NAME or always pass -p.
• Keep compose file sets consistent
  • If you use multiple files, always pass the same -f list for up/down.
• Remove first, then deploy
  • When refactoring services, run down --remove-orphans before up.
• Avoid mixing docker compose and legacy docker-compose with different configs
  • They share semantics but can create separate projects if used differently.

Pitfalls and safety

• Data loss risk
  • docker compose down -v removes volumes. Do not use -v unless you intend to delete data.
• Production impact
  • --remove-orphans will stop containers that might be serving traffic if you rely on them. Confirm before running in prod.
• Hidden global state
  • A lingering COMPOSE_PROJECT_NAME in your environment can change the project name unexpectedly. Check echo $COMPOSE_PROJECT_NAME.
• Multiple compose files
  • If you up with one set of files and down with another, you will leave orphans. Always mirror the -f list.

Performance notes

• up --remove-orphans only removes unmanaged containers; it does not rebuild images unless required.
• down recreates networks on the next up, adding minor startup overhead. Prefer up --remove-orphans for lighter cleanup.
• Keeping a stable project name improves cache reuse for build and avoids duplicate networks.

Tiny FAQ

• What causes "Found orphan containers"?

  • Containers from the same project label exist but are not defined in your current compose configuration.

• Is it safe to use --remove-orphans?

  • Yes, but it stops and removes those containers. Ensure they are not needed.

• How do I keep an old container intentionally?

  • Run it outside Compose or under a different project name (-p othername).

• Can I hide the warning?

  • Set COMPOSE_IGNORE_ORPHANS=1, but the containers will remain.

• Does this apply to docker-compose (v1)?

  • Yes. Use the same flags: docker-compose up -d --remove-orphans and docker-compose down --remove-orphans.