Fix: Docker container name already in use

The Error

You run docker run or docker-compose up and get:

docker: Error response from daemon: Conflict. The container name "/my-app" is already in use
by container "abc123def456". You have to remove (or rename) that container to be able to reuse
that name.

Or from Docker Compose:

Creating my-project_web_1 ... error
ERROR: for web  Cannot create container for service web: Conflict.
The container name "/my-project_web_1" is already in use

Docker requires unique container names. A container with the specified name already exists — either running or stopped.

Why This Happens

Every Docker container has a unique name. When you use --name my-app or Docker Compose assigns a name, Docker checks for existing containers with that name. Stopped containers still occupy the name until they are removed. The Docker daemon treats created, running, paused, restarting, exited, and dead containers all as live entries in the container store — only after docker rm does the name slot free up.

The behavior is deliberate. Container names are user-facing handles; if Docker silently dropped a stopped container to make room for a new one with the same name, you would lose access to the previous container’s logs, exit code, and filesystem layers before you had a chance to inspect them. The downside is that this safety mechanism turns every crash, every CI rerun, and every docker-compose stop/up cycle into a potential name conflict.

Common causes:

• Previous container was stopped but not removed. docker stop does not delete the container.
• Crashed container left behind. A container that exited with an error still occupies the name.
• Docker Compose recreate conflict. Compose cannot recreate a container if the old one still exists.
• Multiple terminal sessions. You ran docker run --name my-app twice without removing the first.
• Script or CI/CD pipeline rerun. A deployment script runs docker run --name on each deployment without cleaning up old containers.
• Docker daemon restart with persistent containers. Containers with a restart policy come back after the daemon restarts, but the names they reclaim may collide with whatever script you ran during the outage.
• Zombie containers from a different Docker context. Switching contexts (Docker Desktop’s “use other Docker engine” toggle, or docker context use) can leave you with two daemons that each think they own the name.

Platform and Environment Differences

The same “name already in use” error has different root causes depending on where Docker runs.

Linux native. This is the simplest environment. The Docker daemon (dockerd) runs directly on the host, and /var/lib/docker/containers/ holds the container state. docker rm removes the directory entry, the name frees up, and the next docker run succeeds. If you hit phantom conflicts on Linux, it usually means a previous docker run succeeded just enough to register the name before crashing — docker ps -a --filter "name=^my-app$" will show it as Created rather than Exited.

macOS (Docker Desktop). Docker Desktop runs a Linux VM (HyperKit on Intel, Virtualization.framework on Apple Silicon) and the Docker daemon lives inside that VM. The macOS Docker CLI is a thin client that talks to the VM over a socket. Two things go wrong here. First, restarting Docker Desktop without first stopping containers leaves them in a weird state when the VM restarts — they show as Created but cannot be inspected. Second, the VM occasionally fails to release container names after a forced quit; docker system prune -f from a fresh Docker Desktop session is the reset button. On Apple Silicon specifically, switching between amd64 and arm64 containers can leave the daemon thinking the old container is still valid even though its filesystem layers were rebuilt for a different arch.

Windows (Docker Desktop with WSL2 backend). Same VM-layer model as macOS, but with WSL2 as the VM. Container names live inside the WSL2 distro docker-desktop, not in your user distro. If you run docker run --name my-app from a PowerShell window and then from a WSL2 Ubuntu shell, both commands talk to the same daemon and conflict — they are not separate spaces despite feeling separate. Worse, if WSL2 shuts down (wsl --shutdown or the laptop suspending), containers with restart: always come back automatically on next start, and any script that assumed a clean slate trips the name conflict immediately.

WSL2 with Docker Engine installed inside the distro (not Docker Desktop). This is a different model: each WSL2 distro has its own dockerd and its own container namespace. Names do not collide across distros, but a single distro that has not been shut down cleanly often leaves containers in a restarting loop after WSL2 restarts. docker ps -a plus docker rm -f $(docker ps -aq) resets it.

Rootless Podman (drop-in docker replacement). Podman uses its own socket per user — $XDG_RUNTIME_DIR/podman/podman.sock — and there is no system-wide daemon. Two different users on the same Linux host can each have a container named my-app without conflict, because they are entirely separate stores. The trap is when a system service (systemd user unit) and an interactive shell both reach the same socket and run uncoordinated cleanups. Podman’s --replace flag (podman run --replace) has worked since Podman 3.x and avoids the issue entirely.

Docker Desktop on Linux. A newer offering (since 2022) that, like the macOS and Windows versions, runs the daemon inside a VM via QEMU. Container names live in the VM, separate from any dockerd you may have installed directly on the host. If you switch between Docker Desktop and host-installed Docker via docker context use desktop-linux vs docker context use default, the same name can exist in both — but each docker rm only affects the active context. Symptoms: docker ps -a shows no container named my-app, but docker run --name my-app still fails. Check docker context ls first.

CI runners (GitHub Actions, GitLab, CircleCI). Hosted runners are usually ephemeral, so name conflicts there mean either two parallel jobs on the same self-hosted runner used the same container name, or a previous job’s cleanup step did not run. Always include a unique suffix (the job ID or run number) in container names: --name my-app-${{ github.run_id }} for GitHub Actions, --name my-app-${CI_JOB_ID} for GitLab. Self-hosted runners should also include a cleanup step that runs docker rm -f for the expected name in a post-job or always() block, so a failed previous run does not poison the next one.

Fix 1: Remove the Existing Container

The most common fix. Remove the old container so you can reuse the name:

docker rm my-app

If the container is still running, stop it first:

docker stop my-app
docker rm my-app

Or force remove a running container:

docker rm -f my-app

Then run your new container:

docker run --name my-app my-image

Pro Tip: Use docker rm -f in scripts and CI/CD pipelines. It removes the container whether it is running, stopped, or already removed (the -f flag does not error on non-existent containers in newer Docker versions).

Fix 2: Use —rm for Auto-Cleanup

Add --rm to docker run so the container is automatically removed when it stops:

docker run --rm --name my-app my-image

This is ideal for:

• Development and testing
• One-off commands
• CI/CD pipeline steps

The container is deleted as soon as it exits, so the name is immediately available for reuse.

Note: --rm removes the container and its anonymous volumes. Do not use it if you need to inspect the container’s logs or filesystem after it stops.

Fix 3: Fix Docker Compose Conflicts

Docker Compose manages container names automatically. If you get name conflicts:

Bring everything down cleanly:

docker-compose down
docker-compose up -d

docker-compose down stops and removes containers, networks, and default volumes. This ensures a clean state.

Remove orphaned containers:

docker-compose down --remove-orphans

If the project name changed (directory was renamed):

# Specify the old project name to clean up
docker-compose -p old-project-name down

# Then start with the new name
docker-compose up -d

Force recreate containers:

docker-compose up -d --force-recreate

This rebuilds containers even if their configuration has not changed.

Common Mistake: Using docker-compose stop instead of docker-compose down between deployments. stop only stops containers — it does not remove them. The next up finds the old containers and tries to start them rather than creating new ones. Use down for a clean state.

Fix 4: Use Unique Container Names

If you need to run multiple instances, use unique names:

With timestamps:

docker run --name "my-app-$(date +%s)" my-image

With random suffixes:

docker run --name "my-app-$(head /dev/urandom | tr -dc a-z0-9 | head -c 6)" my-image

Without a name (Docker assigns a random name):

docker run my-image
# Docker assigns a name like "hungry_einstein"

If you do not need to reference the container by name later, omit --name entirely.

Fix 5: Script-Safe Container Cleanup

In deployment scripts, always clean up before creating:

#!/bin/bash
CONTAINER_NAME="my-app"

# Stop and remove if exists (ignore errors)
docker stop "$CONTAINER_NAME" 2>/dev/null || true
docker rm "$CONTAINER_NAME" 2>/dev/null || true

# Start fresh
docker run -d --name "$CONTAINER_NAME" my-image

Or use docker run --replace (Docker 25.0+):

docker run --replace --name my-app -d my-image

The --replace flag automatically stops and removes any existing container with the same name before creating the new one. This is the cleanest solution for deployment scripts.

Fix 6: Clean Up All Stopped Containers

Remove all stopped containers at once:

docker container prune

Or with force (no confirmation prompt):

docker container prune -f

Remove containers older than 24 hours:

docker container prune --filter "until=24h"

List all stopped containers first:

docker ps -a --filter "status=exited"

Remove all stopped containers manually:

docker rm $(docker ps -aq --filter "status=exited")

For disk space issues from accumulated containers and images, see Fix: Docker no space left on device.

Fix 7: Use Docker Compose Restart Policies

Instead of manually managing container names, use Compose with restart policies:

services:
  web:
    image: my-app:latest
    restart: unless-stopped
    container_name: my-app  # Optional — explicit name

Restart policies:

With restart: unless-stopped, the container automatically restarts after crashes or Docker daemon restarts. You rarely need to docker run again.

Fix 8: Rename Instead of Remove

If you want to keep the old container for debugging:

docker rename my-app my-app-old
docker run --name my-app my-image

Later, inspect the old container:

docker logs my-app-old
docker inspect my-app-old

And remove it when done:

docker rm my-app-old

This pattern is especially useful in production when a container crashes mid-deployment. Rename the broken one with a timestamp suffix (my-app-broken-20260522), let the deployment continue with the original name, then dig through logs and the filesystem at your own pace before removing the renamed shell.

Still Not Working?

If the error persists after removing the container:

Check for the container in a different Docker context:

docker context ls
docker context use default

If docker ps -a shows nothing but docker run --name my-app still conflicts, you are almost certainly looking at the wrong context. Switch to each context in turn and run docker ps -a --filter "name=^my-app$" until you find where the name is held.

Check for Swarm service conflicts. In Docker Swarm mode, services have their own naming. A service container might conflict with a standalone container name.

Check for Docker Desktop bug. On macOS/Windows, Docker Desktop occasionally has stale state. Restart Docker Desktop:

# macOS
osascript -e 'quit app "Docker"' && open -a Docker

# Windows
Restart-Service docker

Check WSL2 for zombie containers from a previous session. If you use Docker Desktop with the WSL2 backend, a wsl --shutdown followed by a new shell can leave Docker thinking containers that were transitioning to exited are still alive. Force a full Docker Desktop restart from the tray icon rather than just closing the terminal.

Check for docker compose (v2) vs docker-compose (v1) using different project names. Compose v1 (Python) and Compose v2 (Go, shipped with modern Docker) hash project names slightly differently when the directory has unusual characters. Running docker-compose up and then docker compose up (note the space) can create two sets of containers with names that look identical but are not, and remove one while leaving the other.

Check for permission issues on the Docker socket. If you see permission errors when trying to remove containers, see Fix: Docker permission denied socket.

Check for port conflicts. If the name is free but the container still cannot start, the port might be in use. See Fix: Docker port is already allocated.

Reset the Docker state file as a last resort. On Linux you can stop the daemon, move /var/lib/docker/containers/<id>/ for the stuck container aside, and restart the daemon. Do not do this on a system with containers you cannot afford to lose — it is destructive and intended for the case where the daemon’s view of reality is permanently corrupted.

If the Docker daemon itself is not running, see Fix: Docker daemon is not running. If your container starts but exits immediately and leaves the name held, the underlying app may be crashing — see Fix: Docker no space left on device for one common cause, and check the container’s logs with docker logs <name> before assuming it is a name-conflict problem.