Connect Docker containers by name

Attach containers to the same user-defined network and connect using a container name or network alias. For a Compose application, use the service name. This avoids hardcoding container IP addresses that can change when instances are replaced.

Create a network and test HTTP

docker network create mynet
docker run -d --name web --network mynet nginx:stable
docker run --rm --network mynet curlimages/curl:latest \
  --fail --silent --show-error http://web:80/

The temporary client has an HTTP tool, so this example does not assume the Nginx image also contains ping or curl. For repeatable diagnostics, select a reviewed client-image version or digest.

For an API already listening on port 8080, the same pattern is http://api:8080/health. The service must listen on an interface reachable from other containers, usually the container's 0.0.0.0, rather than only its own loopback address.

A running container can join an additional network:

docker network connect mynet existing-container

Use --network-alias when you need a deliberate network-scoped name. An explicit --name is useful for predictable commands, but it is not required for Docker to assign a container name.

Compose service discovery

services:
  web:
    image: nginx:stable
  api:
    build: .

With the default Compose networking arrangement, both services join a project network and api resolves by service name. If the API listens on container port 3000, clients on that network use http://api:3000. Publishing a host port is unnecessary for this internal connection, and expose is not a firewall that grants access.

For communication across Compose projects, explicitly attach the required services to a shared external network. Creating that connection also changes which services can reach one another; keep the network membership intentional.

Diagnose the right layer

1. Confirm both containers are attached to the intended network.
2. Resolve the name from the client container, using a tool available in its image.
3. Test the real protocol and container port.
4. Check the application's listener and logs. docker exec api ss -ltn is useful only if ss is installed.

ping api can test name resolution and ICMP reachability when ping is available and permitted. A successful ping does not prove an HTTP or database service is ready. A failed ping does not necessarily mean its TCP service is unreachable.

FAQ

Does the default bridge resolve container names? It does not provide the same automatic name resolution as a user-defined bridge. Legacy links or manually managed host entries can create exceptions, so “names can never work” is too broad. Prefer a user-defined network over legacy --link configuration.

Can one container join several networks? Yes. Be aware that the container can then communicate across those attachments; naming and aliases are scoped to networks.

Why does the name resolve but the connection fail? Check the port, bind address, application readiness, network policy/firewall, and protocol. DNS success establishes only one part of the connection path.

See Docker bridge networks, Compose service configuration.