How to Add a Network Mode in Docker Compose

Set a service’s network_mode under that service in the Compose file. Choose it when the service needs a particular network namespace. If you omit it and do not customize networks, Docker Compose connects the service to the project’s default network, where services can reach one another by service name. A custom network mode is not needed just to enable service-to-service communication. See Docker’s Compose networking guide for the default project-network behavior.

Choose a Docker network mode for a Compose service

Choose the mode based on the network namespace the service should use:

• bridge uses Docker’s built-in default bridge network. It does not select a named network or the Compose project’s default network. When a service needs a named Compose network, configure it with networks instead.
• host shares the host’s network namespace where supported, changing the service’s network isolation.
• none disables networking for the service.
• service:<service-name> shares the network namespace of another Compose service.
• container:<container-name-or-id> refers to a Docker container.

These modes have different connectivity and isolation behavior. In particular, do not set network_mode and networks on the same service; Compose treats them as mutually exclusive options. The Compose service reference documents network_mode, while the service networks reference describes the separate network attachment setting. The examples below describe configuration syntax; they have not been run against a Docker engine.

Configure network_mode in Docker Compose

Put network_mode inside the service entry, using a literal mode or one of the reference forms. For example, a service called app using host mode is represented by the indented lines services:, app:, and network_mode: host. In an actual Compose file, retain the indentation and add the service’s other required settings, such as its image.

Run this example:

service = "app"
mode = "host"
print(f"services:\n  {service}:\n    network_mode: {mode}")

services:
  app:
    network_mode: host

Replace host with bridge, none, service:<service-name>, or container:<container-name-or-id> as appropriate. The bracketed phrases are placeholders: use the actual Compose service name after service: and a container name or ID after container:. For example, service:api refers to a service named api; a Docker network name or ID is not a substitute for either reference.

docker network ls lists Docker networks and their names and IDs. It does not list containers or Compose services, so its output does not identify a value for service: or container:. Use it to inspect available networks, not to discover service or container identifiers. A network’s name or ID is not by itself a network_mode reference in the forms above.

Do not add a top-level Compose version solely to enable network_mode. The current Compose version and name reference describes the top-level version field as obsolete; Compose validates a file against the Compose format it supports.

Account for Docker Swarm networking

The Compose service setting above and Swarm service networking are separate configuration paths. The supplied Swarm pattern attaches a service through the networks key and declares a pre-existing network as external. In Compose syntax, that pattern has a service entry such as app: networks: [host], plus a top-level networks entry that names host and sets external: true. Replace host with the actual external network name. This attaches the service to a network; it does not make networks interchangeable with network_mode or establish that a network is compatible with every mode. The Compose networking guide explains Compose network attachment; create or identify an external network using the deployment’s Swarm setup before referring to it.

Verify the selected network mode

Review the Compose file and confirm network_mode is nested under the intended service, its value uses the right mode form, and any referenced service or container exists in the environment where the service will run. For Swarm, confirm the external network exists and the service references its exact name under networks. docker network ls can show network names and IDs on the Docker host where it runs, but does not verify that a Compose file is valid or that a service can communicate. This article does not claim that these configurations were tested against a running Docker installation.