Fix: port is already allocated

Starting a container that publishes a port fails immediately with one of these messages:

docker: Error response from daemon: driver failed programming external connectivity on endpoint web (3f1c...): Bind for 0.0.0.0:8080 failed: port is already allocated.

Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:5432 -> 127.0.0.1:0: listen tcp 0.0.0.0:5432: bind: address already in use

Why it happens

-p 8080:80 asks Docker to listen on port 8080 of the host and forward it into the container. Only one program can listen on a given address and port. Either another container already publishes that port, or a normal process on the host (a local PostgreSQL, a development server, another Docker Desktop VM) is using it. The container itself is fine; it was created but could not start.

Step 1: Find out what holds the port

First check other containers, because this is the usual cause after a previous run that was never removed:

docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' | grep 8080

If no container shows up, look for a host process. On Linux:

sudo ss -ltnp | grep ':8080'
sudo lsof -iTCP:8080 -sTCP:LISTEN

On macOS:

sudo lsof -iTCP:8080 -sTCP:LISTEN -n -P

On Windows (PowerShell):

Get-NetTCPConnection -LocalPort 8080 -State Listen | Select-Object OwningProcess
Get-Process -Id (Get-NetTCPConnection -LocalPort 8080 -State Listen).OwningProcess

Step 2: Free the port or pick another one

• If the holder is an old container you no longer need: docker rm -f oldname. With Compose, docker compose down in the other project’s directory.
• If it is a host service you want to keep (for example PostgreSQL on 5432), publish the container on a different host port: -p 5433:5432. The container still listens on 5432 inside; only the host side changes.
• If it is a host service you do not need: stop it, for example sudo systemctl stop postgresql on Linux. Careful: stopping a service that other people rely on will interrupt them.
• On Windows, ports can also be reserved by Hyper-V or WSL even when nothing listens. netsh interface ipv4 show excludedportrange protocol=tcp lists those ranges; choosing a port outside them is the simplest fix.

Step 3: Start the container again

The failed container may still exist in the Created state. Remove it before retrying, or simply run docker compose up -d again, which recreates it:

docker rm web
docker run -d --name web -p 8081:80 nginx:1.27
docker ps

Avoid it next time

• Give containers names and use --rm for throwaway runs so stale containers do not pile up.
• Bind development services to localhost only, -p 127.0.0.1:8080:80, which also keeps them off the network.
• In Compose, keep host ports in the .env file ("${APP_PORT:-8000}:8000") so each developer can change them without editing the YAML.

Official documentation

• Docker networking: published ports
• Compose file reference: ports