Containers require DNS resolution to communicate with host services. Docker Desktop provides host.docker.internal as a hostname that points to the internal IP address of the host machine. This feature works automatically on Windows and macOS but requires manual configuration on Linux systems running Docker Engine.
Understanding host.docker.internal on Linux Systems
Docker Desktop creates this special DNS entry automatically on Windows and macOS through its virtual machine layer. The hostname resolves to the host’s gateway address, allowing containers to reach any service running on the host machine.
Linux systems running Docker Engine natively lack this automatic configuration. The absence of a VM layer means containers cannot discover the host address without explicit configuration.
Configuring host.docker.internal for Linux Docker Engine
Docker versions 20.10 and later support the host-gateway value in extra_hosts configuration. This parameter instructs Docker to map host.docker.internal to the gateway IP address.
Docker Compose Configuration
Add the extra_hosts directive to your Docker service configuration in docker-compose.yml:
services:
webapp:
image: webapp:latest
extra_hosts:
- "host.docker.internal:host-gateway"
ports:
- "8080:8080"The host-gateway value resolves to the Docker bridge network gateway, typically 172.17.0.1.
Command Line Configuration for host.docker.internal Linux
Execute containers with the add-host flag when using docker run:
docker run --add-host host.docker.internal:host-gateway \
-p 8080:8080 webapp:latestThis command establishes the DNS mapping for the container session. Services on the host must bind to 0.0.0.0 or the Docker bridge IP to accept connections from containers.
Network Architecture and Connectivity
The Docker bridge network operates on subnet 172.17.0.0/16 by default. Containers receive IP addresses within this range and use the gateway at 172.17.0.1 to reach external networks.
When host.docker.internal resolves to the gateway address, containers can access services listening on the host. The host’s IP configuration determines which services are reachable.
Service Binding Requirements
Services must listen on specific addresses to accept container connections:
| Binding Address | Container Access |
|---|---|
| 127.0.0.1 | Blocked |
| 0.0.0.0 | Allowed |
| 172.17.0.1 | Allowed |
Applications bound to localhost (127.0.0.1) refuse connections from container networks. Binding to 0.0.0.0 allows connections from all network interfaces.
Firewall Configuration for Container-to-Host Communication
Linux firewall rules may block traffic from Docker networks. The ufw firewall requires explicit rules to permit container connections.
Allow traffic from the Docker subnet:
sudo ufw allow from 172.17.0.0/16This rule permits all container-to-host traffic while maintaining security for external connections. Use netstat to monitor network connections and verify container access.
Common Use Cases for host.docker.internal
Database Connections
Containerized applications frequently need access to databases running on the host. Configure the database connection string to use host.docker.internal:
DATABASE_URL=postgresql://user:[email protected]:5432/dbThe database server must listen on 0.0.0.0:5432 to accept these connections.
Microservice Communication
Multiple Docker Compose projects can communicate when services use host.docker.internal. This approach connects separate container environments without complex network configurations.
Development Tool Access
Containers can reach development tools running natively on the host. IDEs, debugging servers, and monitoring tools become accessible through the hostname.
Linux Distribution Compatibility
The host-gateway feature works across major Linux distributions running Docker Engine 20.10 or later. Ubuntu, Debian, Fedora, and Arch Linux support this configuration method.
Docker Desktop for Linux includes automatic host.docker.internal support without manual configuration. The distinction between Docker Desktop and Docker Engine determines whether setup is required.
Production Environment Considerations
host.docker.internal serves development workflows primarily. Production deployments should use proper service discovery mechanisms or explicit IP addresses.
Environment variables provide flexibility across different deployment scenarios:
API_ENDPOINT=${API_ENDPOINT:-http://host.docker.internal:3000}This pattern allows development containers to use host.docker.internal while production containers use configured service addresses. Proper service management ensures reliable container networking.
Security Implications
Container access to host services creates potential security vectors. Limit container permissions and restrict which services bind to accessible addresses.
Network policies in orchestration platforms provide granular control over container communication. Use these mechanisms in production rather than relying on host.docker.internal.
Troubleshooting Connection Failures
Connection errors typically stem from three sources: missing extra_hosts configuration, incorrect service binding, or firewall restrictions.
Verify the hostname resolves correctly inside containers:
docker exec container_name getent hosts host.docker.internalThe command should return the gateway IP address. Check network namespace configuration if resolution fails.
Test connectivity to host services using curl or telnet from within containers. Service binding issues appear as connection refused errors while firewall problems cause timeouts.
FAQs
Why doesn’t host.docker.internal work on my Linux system?
Docker Engine on Linux requires explicit configuration using the host-gateway parameter in extra_hosts. Add this to your docker-compose.yml or docker run command.
What IP address does host.docker.internal resolve to on Linux?
The hostname resolves to Docker’s gateway address, typically 172.17.0.1. This address provides the route from containers to the host system.
Can I use host.docker.internal in production deployments?
This feature suits development environments primarily. Production systems should implement proper service discovery, explicit addressing, or orchestration platform networking features.
How do I allow container access through the Linux firewall?
Run sudo ufw allow from 172.17.0.0/16 to permit traffic from the Docker subnet. Adjust the subnet if using custom bridge networks.
Does WSL2 require host.docker.internal configuration on Linux?
No. Docker Desktop for WSL2 includes automatic host.docker.internal support without manual setup. Only native Linux installations need extra_hosts configuration.
