Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A container cannot start because its published host port is already taken

ErrorError response from daemon: driver failed programming external connectivity on endpoint web: Bind for 0.0.0.0:80 failed: port is already allocated

Short answer

Docker publishes a container port by binding a port on the host, and a port can have only one owner. The error means something else already owns that host port: another container, a service on the machine itself, or a second mapping in your own Compose files. Find the owner first, then stop it or publish your container on a different host port.

  • Applies to Docker Engine 28, Docker Desktop 4.x (macOS and Linux), Docker Compose v2, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run both lookups. The first asks Docker which containers publish the port; the second asks the operating system which process listens on it. Whichever one prints a line is the owner. If both are empty, the port is held by the same Compose project that is starting now (see the third cause).

    docker ps --filter publish=80 --format "table {{.Names}}\t{{.Ports}}"
    sudo ss -ltnp 'sport = :80'
    # macOS: sudo lsof -nP -iTCP:80 -sTCP:LISTEN
  2. 2Match what you see, then jump to its fix

    1. 1The docker ps lookup prints a container, often one from an older project, a forgotten test run, or the same stack started from a different folder. The wording is usually 'port is already allocated'.Another container already publishes that host portFix
    2. 2The docker ps lookup is empty, ss or lsof names a program such as nginx, apache2 or a dev server, and the message says 'address already in use'.A service on the machine itself listens on that portFix
    3. 3Both lookups are empty, or they show a container from this very project, and the error appears when a second service or a second project starts.Your own Compose files publish the same host port twiceFix

What does the error look like?

  • Error response from daemon: driver failed programming external connectivity on endpoint web: Bind for 0.0.0.0:80 failed: port is already allocated
  • Error starting userland proxy: listen tcp4 0.0.0.0:80: bind: address already in use
  • Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:80 -> 127.0.0.1:0: listen tcp 0.0.0.0:80: bind: address already in use

Cause 1 of 3

Another container already publishes that host port

1Check

A published port belongs to a container as long as it runs. List what publishes it, with the project and the image, so you know whether it is safe to stop.

docker ps --filter publish=80 --format "table {{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Ports}}"
docker inspect --format '{{index .Config.Labels "com.docker.compose.project"}}' <container>

2Fix

Stop and remove that container, or if it must keep running, give the new one a different host port. Only the left side of the mapping changes; the container still listens on its own port.

docker stop old-web && docker rm old-web

# or keep both: publish the new container on host port 8080
docker run -d --name web -p 8080:80 nginx

3Verify

The new container is running and its mapping shows the host port you chose.

docker port web
curl -sI http://localhost:8080 | head -1

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

A service on the machine itself listens on that port

1Check

Docker binds the host port itself, so any program already listening on it blocks the container. The process name and PID in the ss output tells you which one.

sudo ss -ltnp 'sport = :80'
systemctl status nginx apache2 --no-pager 2>/dev/null | grep -E 'Active|●'

2Fix

Stop or move that program if the container is meant to replace it, or publish the container on another host port and put the existing web server in front of it as a proxy. To keep a published port off the network, bind it to the loopback address only.

# free the port
sudo systemctl stop nginx && sudo systemctl disable nginx

# or remap, and reach the container only from this machine
docker run -d --name web -p 127.0.0.1:8080:80 nginx

3Verify

ss shows the port free before the start, and Docker's own process afterwards.

sudo ss -ltnp 'sport = :80'
docker run -d --name web2 -p 80:80 nginx && docker ps --filter name=web2

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

Your own Compose files publish the same host port twice

1Check

Two services in one file, or two projects started from different folders, can each map the same host port. Compose publishes every ports entry as written, and with no host IP it binds all interfaces. Print the effective mappings after Compose has merged every file.

docker compose config | grep -nE 'published|target|host_ip'
docker ps --format "table {{.Names}}\t{{.Ports}}"

2Fix

Give each service its own host port. For tools that need any free port, give a range as the published value and Compose assigns one that is available from it, or give only the container port and let the host pick. Quote port values in YAML.

services:
  web:
    ports:
      - "8080:80"
  admin:
    ports:
      - "8000-8010:3000"      # first free port from the range
  db:
    ports:
      - "127.0.0.1:5433:5432"

3Verify

All services start, and the mappings differ.

docker compose up -d
docker compose ps --format "table {{.Service}}\t{{.Ports}}"

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Pick one host port per project and write it into the Compose file, so two stacks never choose the same one by accident.
  • Bind development databases and admin tools to 127.0.0.1; without a host IP Docker binds every interface.
  • Use docker compose down when you finish, so the stack's ports are released.
  • Check the port before starting: docker ps --filter publish=<port> and ss in the same command.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.