Introduction

extra_hosts in Docker Compose is often misunderstood. It does not ask Docker to resolve another service name for you; it writes fixed entries into /etc/hosts inside the container. If you want one service to find another service by name, the normal solution is Docker networking and service DNS, not extra_hosts.

What extra_hosts Actually Does

When Compose starts a container, extra_hosts adds static hostname-to-IP mappings. That is equivalent to editing /etc/hosts inside the container.

1services:
2  app:
3    image: nginx:alpine
4    extra_hosts:
5      - "legacy-db:10.10.0.15"

Inside the app container, resolving legacy-db now returns 10.10.0.15. This is useful for external systems with fixed addresses, on-prem endpoints, or temporary test mappings. It is not a dynamic reference to another Compose service.

Use Service Names for Container-to-Container Resolution

Compose already creates DNS records for service names on the same network. If your goal is "web should reach db", you usually need nothing more than the service name.

1services:
2  web:
3    image: python:3.12-slim
4    depends_on:
5      - db
6    command: ["python", "-c", "print('connect to host db on port 5432')"]
7
8  db:
9    image: postgres:16
10    environment:
11      POSTGRES_PASSWORD: secret

From web, the hostname db resolves automatically through Docker's embedded DNS. That is the correct Compose-native approach.

If you need an additional hostname, use a network alias rather than extra_hosts.

1services:
2  api:
3    image: nginx:alpine
4    networks:
5      default:
6        aliases:
7          - internal-api

Now other containers on the same network can resolve both api and internal-api.

Why Container Names Do Not Belong in extra_hosts

The common question is whether extra_hosts can say "map this hostname to the current IP of container db". In practice, that is the wrong abstraction because container IPs are ephemeral. They can change when you recreate services, scale services, or restart a project.

Static host entries and dynamic container IPs do not mix well. If you manually discover a container IP and place it in extra_hosts, the mapping becomes stale the next time networking changes.

That is why Compose gives you service DNS. It solves exactly this problem without hardcoding internal IP addresses.

Special Case: Reaching the Host Machine

Sometimes the real goal is not another container, but the host machine. In that case extra_hosts can be useful with host-gateway.

1services:
2  app:
3    image: curlimages/curl:8.7.1
4    extra_hosts:
5      - "host.docker.internal:host-gateway"
6    command: ["sh", "-c", "getent hosts host.docker.internal"]

This is different from resolving a Compose service. It maps a known host alias to the Docker host gateway in a way Docker understands.

How to Debug Name Resolution

When networking behavior is unclear, inspect the container directly. First, verify the generated hosts file.

docker compose exec app cat /etc/hosts

Then check DNS resolution for service names:

docker compose exec app getent hosts db
docker compose exec app getent hosts internal-api

If db resolves but the custom hostname does not, the problem is probably alias configuration. If only the extra_hosts name resolves, then you are reading a static mapping rather than Docker DNS.

Common Pitfalls

• Using extra_hosts to point to another Compose service instead of relying on service DNS.
• Hardcoding container IP addresses that change after restart or redeploy.
• Confusing container_name with a stable network identity across environments.
• Forgetting that extra_hosts edits /etc/hosts, not Docker's DNS server.
• Solving host-machine access and container-to-container access with the same pattern even though they are different problems.

Summary

• 'extra_hosts creates static hostname entries inside a container.'
• It is useful for fixed external IP mappings, not for dynamic Compose service discovery.
• Compose service names already resolve automatically on the same network.
• Use network aliases when you need an extra internal hostname.
• For host-machine access, host-gateway is a valid extra_hosts use case.