This guide shows how to let a Docker container reach services running on the host machine’s network, such as a local database, API, or web server. You’ll learn the two main methods — using host.docker.internal and the host network mode — and how to choose between them. No prior Docker networking knowledge is required, but you should have Docker installed and be comfortable running basic commands.
What You’ll Need
- Docker installed (Docker Desktop on Windows/macOS, or Docker Engine on Linux)
- A host service running on a known port (e.g., MySQL on 3306)
- Basic command-line access to your terminal or PowerShell
Step-by-Step
- Identify the host service and port. Confirm the service is listening on the host (e.g.,
localhost:5432for PostgreSQL). Usenetstat -an | grep 5432(Linux/macOS) ornetstat -an | findstr 5432(Windows) to verify. - Decide which method to use. The easiest and most portable is
host.docker.internal, which works on Docker Desktop (Windows/macOS) and on Linux if you add a special flag. The alternative is thehostnetwork mode, which is Linux-only and gives the container direct access to the host’s network stack. - For Docker Desktop (Windows/macOS): Run your container with
--add-host=host.docker.internal:host-gateway(optional but recommended) and then usehost.docker.internalas the hostname inside the container. For example, to connect to a PostgreSQL on the host:docker run -it --rm postgres:13 psql -h host.docker.internal -U myuser. - For Linux with default bridge network: Start your container with
--add-host=host.docker.internal:host-gateway. Then usehost.docker.internalin your application’s connection string. Example:docker run --add-host=host.docker.internal:host-gateway myapp. - Alternative: use the host network mode (Linux only). Run your container with
--network host. This makes the container share the host’s network namespace, solocalhostinside the container refers to the host. Example:docker run --network host myapp. This works only on Linux; on Windows/macOS it has limited support. - Test the connection. Inside the container, use tools like
curl,nc, or your application’s client to connect to the host service. For example,curl http://host.docker.internal:8080ornc -zv host.docker.internal 3306. - Update your application configuration. Replace any hardcoded
localhostor127.0.0.1withhost.docker.internal(or use the host network mode and keeplocalhost). This is often done via environment variables, e.g.,DB_HOST=host.docker.internal. - If the host service is bound only to 127.0.0.1, you may need to bind it to 0.0.0.0 as well. For example, start your database with
--bind-address=0.0.0.0(MySQL) orlisten_addresses = '*'(PostgreSQL). This is a common gotcha.
Common Mistakes
- Using
localhostinside the container. In the default bridge network,localhostrefers to the container itself, not the host. Always usehost.docker.internalunless you’re on the host network. - Forgetting the
--add-hostflag on Linux. On Linux,host.docker.internalis not automatically added; without the flag, the name won’t resolve. - Host service bound only to 127.0.0.1. Many services default to listening only on the loopback interface, which the container cannot reach. Change the bind address to 0.0.0.0 or the Docker bridge IP.
- Using host network mode on Docker Desktop. It does not work as expected on Windows/macOS; the container still runs inside a VM. Stick with
host.docker.internalthere. - Firewall blocking. Even if the service listens on all interfaces, a host firewall (like ufw or Windows Firewall) may block connections from Docker’s virtual network. Allow the port for the Docker subnet.
Tips
- Prefer
host.docker.internalfor portability. It works across Docker Desktop and Linux (with the flag), so your app code stays the same. - Use environment variables for connection details. Set
DB_HOST=host.docker.internalin yourdocker runcommand ordocker-compose.ymlto avoid hardcoding. - In docker-compose, add
extra_hosts: - "host.docker.internal:host-gateway"to your service definition. - For development, consider using Docker Compose. It lets you define the network and host mapping clearly, making it easier for teammates.
- Check the Docker bridge IP. If
host.docker.internalfails, you can find the host’s IP on the Docker bridge (usually172.17.0.1on Linux) and use that directly.
Troubleshooting
- Cannot resolve
host.docker.internal. On Linux, ensure you added--add-host=host.docker.internal:host-gateway. On Docker Desktop, restart Docker if the name isn’t resolving. - Connection refused. Verify the host service is running and listening on the expected port. Check if it’s bound to 127.0.0.1 only; if so, change the bind address.
- Timeout instead of refusal. A firewall is likely blocking the traffic. Temporarily disable the firewall (or add a rule) to test. On Linux, check
iptablesrules; on Windows, check Windows Defender Firewall. - Host network mode gives no internet. This is unusual; the host network should share the host’s connectivity. If DNS fails, check your host’s DNS settings.
- Docker Desktop on Windows: still can’t connect. Ensure the service is listening on all interfaces (use
netstat -anto see if it’s 0.0.0.0 or 127.0.0.1). Also, try using the host’s LAN IP instead ofhost.docker.internal. - Inside the container,
curlis not installed. Usedocker exec -it <container> shand install curl or usewget. Alternatively, test with a language’s built-in tools (e.g., Python’surllib).
Frequently Asked Questions
- Can I use
host.docker.internalon Linux without extra flags? No, on Linux you must add--add-host=host.docker.internal:host-gatewayto yourdocker runcommand orextra_hostsin compose. - What is the difference between
host.docker.internaland--network host? The former is a DNS name that resolves to the host’s IP from the container’s perspective, while the latter makes the container share the host’s network stack entirely, solocalhostworks but the container loses its own network namespace. - Does
--network hostwork on Docker Desktop? On Windows and macOS, Docker Desktop runs containers in a VM, so host networking is not fully supported. It may work in some cases but is not reliable; usehost.docker.internalinstead. - Why does my container see the host’s service as
localhost? Only when using--network host. In the default bridge network,localhostis the container itself. - Can I access a host port that is bound to 127.0.0.1? Not directly. You must change the service to bind to 0.0.0.0 or the Docker bridge IP, or use
--network host(Linux only). - Is it safe to expose host services to Docker containers? Generally yes, but be aware that any container on the same Docker network can reach those ports. Use firewalls and only bind to the Docker bridge interface if you want to restrict access.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- API Governance for Public Data: What Growing Portfolios Need
- Samsung Smart Speaker Rollable Display: Facts
- HP 9730e: Wide Prints, Not A3 Scans
- What 8888 Does When You Use It as DNS Server
- Credential Manager: Seamless Sign-In Explained
- Enterprise AI Hidden Cost: Data Architecture ROI