How to fix dial tcp: lookup host.docker.internal: no such host in Docker

The most common solution for Linux systems is to add the extra_hosts configuration to your docker-compose.yml file:

services:
  your-service:
    image: your-image
    extra_hosts:
      - "host.docker.internal:host-gateway"

The special value host-gateway tells Docker to replace it with the host's gateway IP address. This adds an entry to the container's /etc/hosts file.

Apply to all services that need host access:

services:
  app:
    image: node:18
    extra_hosts:
      - "host.docker.internal:host-gateway"

  worker:
    image: python:3.11
    extra_hosts:
      - "host.docker.internal:host-gateway"

After making this change, restart your containers:

docker compose down
docker compose up -d

When running containers with docker run instead of Docker Compose, use the --add-host flag:

docker run --add-host=host.docker.internal:host-gateway your-image

This achieves the same effect as the docker-compose.yml configuration.

Example with additional options:

docker run -d \
  --name my-app \
  --add-host=host.docker.internal:host-gateway \
  -p 3000:3000 \
  my-app-image

Verify the host entry was added:

docker exec my-app cat /etc/hosts

You should see a line like:

172.17.0.1    host.docker.internal

The host-gateway special value requires Docker Engine version 20.10.0 or later (released December 2020).

Check your Docker version:

docker --version

If you see "invalid IP address in add-host: host-gateway", you need to upgrade Docker.

Upgrade Docker on Ubuntu/Debian:

# Remove old version
sudo apt remove docker docker-engine docker.io containerd runc

# Install latest Docker
curl -fsSL https://get.docker.com | sudo sh

# Verify version
docker --version

Upgrade Docker on CentOS/RHEL/Fedora:

sudo yum remove docker docker-common docker-selinux docker-engine
curl -fsSL https://get.docker.com | sudo sh
docker --version

Docker Desktop for Linux includes host.docker.internal support out of the box, similar to macOS and Windows.

Install Docker Desktop on Ubuntu:

# Download the .deb package from Docker's website
# https://docs.docker.com/desktop/install/ubuntu/

sudo apt install ./docker-desktop-<version>-amd64.deb

Enable host.docker.internal in Docker Desktop:
1. Open Docker Desktop
2. Go to Settings (gear icon)
3. Navigate to Resources > Network
4. Ensure "Enable host.docker.internal" is checked
5. Click "Apply & Restart"

With Docker Desktop, host.docker.internal resolves automatically without extra configuration.

If you don't need network isolation, you can use host network mode where the container shares the host's network stack:

With docker-compose.yml:

services:
  your-service:
    image: your-image
    network_mode: host

With docker run:

docker run --network host your-image

Important considerations:
- The container uses the host's IP address directly
- No port mapping needed (or possible) - ports bind directly to host
- Container can access localhost services on the host
- Reduces network isolation - use with caution in production
- May not work on macOS/Windows Docker Desktop (host networking is Linux-only)

This approach eliminates the need for host.docker.internal entirely because localhost in the container refers to the actual host.

If host-gateway is not available, you can manually specify the Docker bridge gateway IP:

Find the gateway IP:

docker network inspect bridge --format '{{range .IPAM.Config}}{{.Gateway}}{{end}}'

This typically returns 172.17.0.1.

Use the IP in docker-compose.yml:

services:
  your-service:
    image: your-image
    extra_hosts:
      - "host.docker.internal:172.17.0.1"

Or with docker run:

docker run --add-host=host.docker.internal:172.17.0.1 your-image

Note: The gateway IP can vary if you have multiple Docker networks. You may need to adjust it based on your network configuration.

Even with correct DNS resolution, firewall rules may block connections from containers to the host.

Allow Docker bridge network on Ubuntu (ufw):

# Allow from Docker bridge subnet
sudo ufw allow from 172.17.0.0/16

# Or more specifically, allow a port
sudo ufw allow from 172.17.0.0/16 to any port 5432

Allow on CentOS/RHEL (firewalld):

# Add Docker zone
sudo firewall-cmd --permanent --zone=docker --add-source=172.17.0.0/16
sudo firewall-cmd --permanent --zone=docker --add-port=5432/tcp
sudo firewall-cmd --reload

Test connectivity from container:

docker run --rm --add-host=host.docker.internal:host-gateway alpine \
  sh -c "apk add --no-cache curl && curl -v host.docker.internal:5432"

Replace 5432 with the port of the service you're trying to reach.

Services on the host must listen on an interface accessible to containers, not just localhost.

Problem: Service only listens on 127.0.0.1

# This only accepts local connections
postgres -h 127.0.0.1 -p 5432

Solution: Bind to 0.0.0.0 or the Docker bridge IP

# This accepts connections from any interface
postgres -h 0.0.0.0 -p 5432

# Or bind to the Docker bridge specifically
postgres -h 172.17.0.1 -p 5432

For PostgreSQL (postgresql.conf):

listen_addresses = '*'

For MySQL (my.cnf):

bind-address = 0.0.0.0

For Node.js applications:

// Instead of
app.listen(3000, '127.0.0.1');
// Use
app.listen(3000, '0.0.0.0');

Security note: When binding to 0.0.0.0, ensure your firewall only allows connections from trusted sources.