Docker Compose host Network Mode Not Working as Expected on macOS

network_mode: host not working as expected on macOS isn't a bug in your configuration — Docker Desktop on macOS runs containers inside a lightweight Linux virtual machine, and "host" networking refers to that VM's own network namespace, not your actual Mac's network directly, which is a fundamentally different situation than on native Linux.

The Problem

A service configured with host networking, expecting to bind directly to the Mac's own localhost and be reachable at localhost:PORT without any port mapping, doesn't behave as expected:

services:
  app:
    image: your-app
    network_mode: host

On Linux, this would make the container's ports directly accessible on the host's own localhost without needing any explicit port mapping — on macOS, this same configuration often doesn't provide equivalent behavior at all.

Why It Happens

On native Linux, Docker containers can share the host's actual network namespace directly, since Linux containers and the Linux host are running in the same underlying kernel — network_mode: host genuinely attaches the container to the host machine's real network stack. On macOS, Docker Desktop runs Linux containers inside a lightweight virtual machine (since macOS itself doesn't run Linux containers natively) — so "host" networking, even when configured, refers to that VM's own internal network namespace, not your actual Mac's network interfaces directly. This means a container using host networking is genuinely sharing the network namespace of the Docker Desktop VM, which is not the same thing as your Mac's own localhost from the perspective of applications running directly on macOS itself.

The Fix

For most use cases on macOS, use standard, explicit port mapping instead of relying on host networking — this is the well-supported, expected pattern for Docker Desktop on Mac, and provides equivalent practical functionality for the vast majority of use cases that might otherwise reach for host networking:

services:
  app:
    image: your-app
    ports:
      - "3000:3000"

With explicit port mapping, the container's port 3000 becomes accessible at localhost:3000 from your actual Mac, which is genuinely the behavior most people actually want when they reach for host networking in the first place — the difference is mainly relevant for edge cases specifically requiring genuine host-level network namespace sharing, which explicit port mapping doesn't provide, but which most typical development or application scenarios don't actually require.

If your specific use case genuinely requires something host networking would provide on Linux (like a container needing to see and interact with every network interface on the host directly, not just have specific ports forwarded), recognize this is a case where Docker Desktop on macOS has a fundamental architectural limitation compared to native Linux Docker, not something a configuration adjustment alone can fully replicate — the VM layer is an inherent part of how Docker works on macOS, not an optional or bypassable detail.

For accessing services running directly on your Mac (outside of Docker) from within a container, use Docker Desktop's special DNS name specifically provided for this purpose, rather than attempting to use host networking to achieve the same result:

# From inside a container, reach services running on the Mac host itself:
curl http://host.docker.internal:8080

host.docker.internal is a Docker Desktop-specific DNS name that resolves to the actual host machine, working around the VM networking layer specifically for this common "container needs to reach something on the host" scenario, without requiring host networking mode at all.

If you're developing something that will eventually run on Linux with genuine host networking, and need to test that specific behavior, recognize that macOS simply cannot fully replicate it locally due to the fundamental VM-based architecture — testing on an actual Linux machine or a Linux-based CI environment is necessary for validating true host-networking-dependent behavior, rather than trying to force equivalent behavior locally on macOS.

Still Not Working?

If you're specifically troubleshooting why a service configured with host networking mode on macOS seems to run without error but simply isn't reachable at all, confirm you're not conflating "no error" with "working as expected" — Docker Desktop may accept the network_mode: host configuration without complaint (since it's syntactically valid), while the actual practical networking behavior still differs meaningfully from genuine Linux host networking, meaning the absence of a configuration error doesn't confirm the behavior you're actually expecting is genuinely happening underneath.