How to Configure host.docker.internal on Linux

To connect from a Linux container to a service on its Docker host, create the container with --add-host=host.docker.internal:host-gateway on a Docker Engine setup that supports the host-gateway value. Then send the request to host.docker.internal and the service’s listening port. This is traffic from the container to the host; reaching a container from the host is a separate task, usually handled with a published port such as -p 8080:80.

What host.docker.internal Means on Linux

host.docker.internal is a hostname a container can use to address its host. It is not a shell command, and on Linux Docker Engine it may need to be mapped when the container is created. The special host-gateway value lets Docker supply the gateway address for that Engine configuration, instead of requiring you to guess a bridge IP. Support for this value depends on the Docker Engine setup; if Docker rejects it, check the installed Engine’s documentation or use the host address configured for your network.

The mapping only affects the container that receives it. It does not start a host service, publish a container port, or make a service listening only inside another container available on the host.

Add host.docker.internal to a Linux Container

Add the mapping to the docker run command when creating the container:

docker run --rm -it --add-host=host.docker.internal:host-gateway IMAGE COMMAND

Replace IMAGE and COMMAND with the image and process you need. For a long-running application, add the same --add-host option to its service configuration and recreate the container; a mapping cannot be added to an already-running container. The option can be used with a user-defined network as well, but a custom network is not required just to use this host name.

Verify Host Connectivity from the Container

Start a service on the host that accepts connections on an address reachable from the container. For a temporary HTTP check, run python3 -m http.server 8000 --bind 0.0.0.0 on the host. Binding to 0.0.0.0 makes this test server listen on the host’s network interfaces; use it only where the host firewall and network exposure are appropriate. Keep the server running while you test.

Create a test container with the mapping and request the same port. For example, if Docker can pull the curlimages/curl image, run docker run --rm --add-host=host.docker.internal:host-gateway curlimages/curl:latest http://host.docker.internal:8000/. This image includes curl; with another image, ensure a suitable HTTP client is installed. A response from the server, such as an HTTP directory listing, confirms that name resolution, routing, and the service port work together. This Docker and host-service check depends on your local Docker Engine and network, so it is not executed by this article’s isolated code runner.

Troubleshoot Connection Failures

• If the name does not resolve, confirm the container was created with the --add-host=host.docker.internal:host-gateway mapping and that the Docker Engine supports host-gateway. Recreate the container after changing its configuration.
• If the name resolves but the request times out or is refused, confirm the host service is running and listening on the expected port. A service bound only to 127.0.0.1 may accept host-local requests while rejecting connections arriving through the container network; configure a reachable bind address and limit access with the host firewall.
• Check that the URL uses the service’s actual port. The port in the container’s request is the host service port; Docker’s -p option is for publishing a container port and is not needed for this direction of traffic.
• If the mapping is present and the service is reachable from the host but not the container, inspect host firewall rules and Docker Engine network configuration. Do not assume 172.17.0.1 is universal or treat it as localhost; bridge addresses vary by setup.

FAQ

What does host.docker.internal do? It gives a container a hostname for connecting to a service on its host, when the hostname is mapped for that container.

Is Linux setup different from Docker Desktop? Yes. This article covers Linux Docker Engine, where you can add the host-gateway mapping at container creation. Docker Desktop provides its own host networking behavior; use the documentation for the platform and Engine you are running.

Do I need a custom Docker network? No. The --add-host mapping is sufficient for this hostname on a supported Engine. A custom network may be useful for other isolation or service-discovery needs.

How can I test the connection? Run a host service on a reachable interface and port, then request http://host.docker.internal:PORT/ from a container created with the mapping. Ensure the container image has an HTTP client such as curl and that the host firewall permits the traffic.