Technology · PRACTICAL GUIDE
Docker Compose found orphan containers? Audit project ownership before removing them
An orphan warning does not prove a container is disposable. Confirm the effective Compose project, inspect ownership labels and data mounts, distinguish renamed services from project-name collisions and one-off runs, then choose the smallest safe action.
Docker Compose calls a container an orphan when it belongs to the current project identity but its service is not present in the effective Compose model being used by the command. That can be the expected result of a service rename, but it can also reveal two unrelated files sharing a project name, an old file set, or a stopped one-off run container.
The warning is therefore evidence, not permission to delete. The safe question is not simply whether `--remove-orphans` exists. It is which project and service created each named container, whether the current configuration still intends to manage it, and whether its mounts contain data that must survive.
This guide starts with read-only commands. It does not recommend a global prune, does not delete named or external volumes, and does not silence the warning until ownership is understood. The result is a small ownership ledger and one scoped action.
1. Capture the exact warning and freeze the cleanup decision
Save the full warning, the command that produced it, the working directory and every `-f`, `--project-directory`, `-p` or `--project-name` argument. Do not run `docker container prune`, `docker compose down -v`, or repeat a command with `--remove-orphans` while the ownership question is open.
Record `docker compose version`, the active Docker context, and the relevant Compose filenames. If automation launched the command, preserve the environment that can affect project naming, especially `COMPOSE_PROJECT_NAME` and any `.env` file chosen for that invocation.
List all named containers from the warning with `docker ps -a --no-trunc` and record their IDs, status and names. Names are useful clues, but labels and the effective Compose model are the ownership evidence.
2. Resolve the effective Compose project name, not the filename you remember
Docker documents a precedence order for the project name: the `-p` command-line flag, `COMPOSE_PROJECT_NAME`, the last top-level `name` across the specified files, the base name of the project directory, and finally the current directory. Reconstruct the exact invocation before assuming two files are separate projects.
Render the model with the same files, profiles, environment and project options, using `docker compose config` and the appropriate name-printing option supported by the installed version. Save the resulting project name and service list without exposing secret values.
Two repositories can collide when both are launched from similarly named directories such as `docker`, or when automation supplies the same explicit project name. In that branch the warned container may be valid for the other application. Isolate the projects with stable, distinct names; do not remove the other project's container just to clear this warning.
3. Read the Compose ownership labels on every warned container
Inspect each exact container ID and record `com.docker.compose.project`, `com.docker.compose.service`, `com.docker.compose.project.config_files`, `com.docker.compose.project.working_dir`, and any one-off indicator that the installed Compose version provides. Use the JSON output from `docker inspect` rather than inferring ownership from a truncated name.
Compare the project label with the effective project name from the current invocation. A different project label is a stop condition: investigate why the warning grouped it with this run before deleting anything. A matching project label with a service absent from the rendered model is a genuine orphan candidate, not yet proof that removal is safe.
Compare recorded config-file and working-directory labels with the current file set. This can expose a renamed file, a changed `-f` order, deployment automation running from another directory, or an older Compose invocation that intentionally managed additional services.
4. Distinguish the four common branches
A renamed or deleted service leaves a container whose project label matches and whose old service label no longer appears in the current model. Confirm the change in version control or deployment records before treating it as stale.
A project-name collision shows matching project identity but different intended applications or file roots. Give each application a stable unique project name and rerun inspection. Removing containers is not the first fix because the wrong project would simply collide again.
A one-off `docker compose run` container can remain stopped after the command or an interrupted workflow. An upstream issue demonstrates a version-specific case in which repeated run commands accumulated containers and warnings. Keep that as one branch: check labels, state, exit code and version before generalizing it.
An old file-set branch occurs when the same project is intentionally composed from different `-f` combinations or profiles. A service absent today may still be expected under another supported invocation. Document which model owns it before cleanup.
5. Audit mounts and volumes before touching the container
For each candidate, record bind mounts, named volumes and anonymous volumes from `docker inspect`. A stopped container can still be the easiest map to data whose purpose is not documented elsewhere. Verify backup and restore expectations with the service owner.
The Compose down reference separates container and network removal from volume removal. Named volumes declared by the application are not the same as disposable container layers, and external volumes are managed outside the Compose project. Never add `-v` merely because the warning says orphan.
If a container exposes a port or still runs a workload, identify its users and dependencies before stopping it. An orphan classification means absent from the current model; it does not prove the workload or data is no longer needed.
6. Choose the narrowest action and record the result
When the container is confirmed stale, belongs to the current project, has no needed workload, and its data is preserved, use the project-scoped Compose command appropriate to the same file set and project name. `docker compose up --remove-orphans` is documented to remove containers for services not defined in the current file, so its scope must be correct first.
When the cause is a name collision, change the project identity and rerun without deletion. When the container is an expected alternate-profile or alternate-file service, keep it and document the supported invocation. When a one-off run container is the cause, prefer the command's normal lifecycle controls and a version-specific fix over a global prune.
After the action, rerun the original command with the same context and capture the new warning state. Reinspect surviving containers and confirm that unrelated projects, ports, networks and data mounts are unchanged.
Evidence | Likely branch | Smallest safe action Project label differs from the intended project | Ownership mismatch | Stop; resolve invocation and naming before removal Same project, old service absent after an intentional rename | Confirmed stale service | Preserve data, then use scoped orphan removal Same inferred name across unrelated file roots | Project-name collision | Assign stable distinct project names; keep valid containers Stopped one-off container with matching run evidence | One-off lifecycle | Inspect exit/version, then remove only the confirmed run container Service belongs to an alternate supported file/profile set | Expected resource | Keep it and document the owning invocation
7. Validate cleanup and prepare a support-ready ledger
Acceptance is specific: every named warning container has a documented project and service owner; retained containers correspond to supported invocations; removed containers were proven stale; needed mounts remain present; and the original Compose command no longer interferes with another project.
For support, include sanitized Compose and Engine versions, Docker context, effective project name, file order, container IDs, project/service/config-file labels, state and exit code, and mount types. Keep credentials, secret environment values and private registry tokens out of the report.
Escalate a possible Compose regression only after project-name precedence, file-set differences, labels, one-off state and ordinary lifecycle behavior are accounted for. A warning that mentions `--remove-orphans` is not by itself proof that the flag is accepted by the exact subcommand or fixes the observed branch.
Frequently asked questions
What does a Docker Compose orphan container mean? It means a container is associated with the effective Compose project identity but its service is not in the current model. The reason may be a real service removal, a project-name collision, a different file/profile set or a one-off run container.
Is `--remove-orphans` always safe? No. It is safe only after the current project scope is correct, every candidate is truly stale, and needed mounts or data are preserved. The flag follows the current Compose model; a wrong project name or file set makes that scope dangerous.
Why do two unrelated Compose files see each other's containers? They can resolve to the same project name through directory defaults, environment variables, top-level name or an explicit -p flag. Give unrelated applications stable distinct project names.
Should I use `docker container prune` to clear the warning? Not as the first step. A global prune has a broader scope and does not explain ownership. Inspect labels, project naming, state and mounts, then remove only containers proven stale.
