The 'address already in use' error occurs when Docker tries to bind a container port to a host port that's already occupied by another process or container. Identify and stop the conflicting process, or use a different port.
The "address already in use" error in Docker happens when you try to start a container that maps a port to the host, but that port is already being used by another process. When Docker starts a container with port mapping (e.g., `-p 3000:3000`), it needs to create a "userland proxy" that listens on that host port and forwards traffic to the container. If another application, service, or Docker container is already listening on that port, the operating system refuses to let Docker bind to it, resulting in this error. This is a networking conflict at the operating system level. Only one process can listen on a specific IP address and port combination at any given time. Common culprums include development servers running directly on the host, other Docker containers, or system services like web servers (nginx, Apache) or databases.
Find out which process is occupying the port using lsof or netstat:
# On Linux/macOS with lsof
sudo lsof -i :3000
# Or use netstat
sudo netstat -tlnp | grep :3000
# On macOS, you can also use
lsof -nP -iTCP:3000 | grep LISTENThe output will show the process name and PID using the port. Look at the COMMAND and PID columns to identify the culprit.
The port might be used by another Docker container:
# List all running containers with their ports
docker ps --format "table {{.Names}} {{.Ports}}"
# Or find containers using a specific port
docker ps | grep 3000If another container is using the port, stop it:
docker stop <container_name_or_id>Once you've identified the process, you can stop it:
# Kill by PID (replace 12345 with the actual PID)
kill 12345
# If it doesn't stop, force kill
kill -9 12345
# Or stop the service if it's a system service
sudo systemctl stop nginx
sudo systemctl stop apache2For development servers, simply stop them with Ctrl+C in their terminal or close the IDE that started them.
If you can't or don't want to stop the other process, map to a different host port:
# Change the host port (first number) while keeping container port
docker run -p 3001:3000 myimage
# In docker-compose.yml, change:
ports:
- "3001:3000" # Host:ContainerRemember to update any references to the port in your application or browser.
Sometimes stopped containers can still hold ports briefly. Clean them up:
# Remove all stopped containers
docker container prune
# Or remove specific container
docker rm <container_name>
# Force remove if needed
docker rm -f <container_name>Then try starting your container again.
In rare cases, Docker's networking state gets corrupted. Restart the daemon:
# Linux
sudo systemctl restart docker
# macOS (Docker Desktop)
# Click Docker icon > Restart
# Or from command line on macOS
killall Docker && open /Applications/Docker.appWait for Docker to fully restart, then try your container again.
On macOS, certain system features use common ports:
Port 5000 (AirPlay Receiver):
1. Open System Settings > General > AirDrop & Handoff
2. Turn off "AirPlay Receiver"
Port 7000 (AirPlay):
Same as above - disable AirPlay Receiver.
Alternatively, use a different port for your container instead of disabling system features.
### Understanding Docker Port Mapping
When you use -p HOST_PORT:CONTAINER_PORT, Docker creates a userland proxy process that:
1. Listens on the host's IP address and port
2. Forwards incoming connections to the container's internal port
3. Handles the network address translation (NAT)
You can see these proxy processes with ps aux | grep docker-proxy.
### Binding to Specific Interfaces
You can bind to a specific IP instead of all interfaces (0.0.0.0):
# Only accessible from localhost
docker run -p 127.0.0.1:3000:3000 myimage
# Bind to specific network interface
docker run -p 192.168.1.100:3000:3000 myimageThis might help if another service is bound to a different interface on the same port.
### Docker Compose Port Conflicts
With multiple services in docker-compose, ensure each uses a unique host port:
services:
web:
ports:
- "3000:3000"
api:
ports:
- "3001:3000" # Different host port, same container port is OK### Preventing Port Conflicts in CI/CD
In CI environments, use dynamic port allocation:
# Let Docker choose an available host port
docker run -p 3000 myimage
# Find the assigned port
docker port <container_id> 3000### Linux: systemd-resolved Port 53 Conflict
If port 53 conflicts with systemd-resolved:
# Option 1: Disable the stub listener
sudo sed -i 's/#DNSStubListener=yes/DNSStubListener=no/' /etc/systemd/resolved.conf
sudo systemctl restart systemd-resolved
# Option 2: Bind to a specific IP instead of 0.0.0.0
docker run -p 127.0.0.2:53:53 my-dns-containerdockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec