Define and manage networks in Docker Compose

{{% include "compose/networks.md" %}}

To use a network across multiple services, you must explicitly grant each service access by using the networks attribute within the services top-level element. The networks top-level element has additional syntax that provides more granular control.

Examples

Basic example

In the following example, at runtime, networks front-tier and back-tier are created and the frontend service is connected to front-tier and back-tier networks.

services:
  frontend:
    image: example/webapp
    networks:
      - front-tier
      - back-tier

networks:
  front-tier:
  back-tier:

Advanced example

services:
  proxy:
    build: ./proxy
    networks:
      - frontend
  app:
    build: ./app
    networks:
      - frontend
      - backend
  db:
    image: postgres:18
    networks:
      - backend

networks:
  frontend:
    # Specify driver options
    driver: bridge
    driver_opts:
      com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"
  backend:
    # Use a custom driver
    driver: custom-driver

This example shows a Compose file which defines two custom networks. The proxy service is isolated from the db service, because they do not share a network in common. Only app can talk to both.

The default network

When a Compose file doesn't declare explicit networks, Compose uses an implicit default network. Services without an explicit networks declaration are connected by Compose to this default network:

services:
  some-service:
    image: foo

This example is actually equivalent to:

services:
  some-service:
    image: foo
    networks:
      default: {}  
networks:
  default: {}      

You can customize the default network with an explicit declaration:

networks:
  default: 
    name: a_network # Use a custom name
    driver_opts:    # pass options to driver for network creation
      com.docker.network.bridge.host_binding_ipv4: 127.0.0.1

For options, see the Docker Engine docs.

Attributes

attachable

If attachable is set to true, then standalone containers should be able to attach to this network, in addition to services. If a standalone container attaches to the network, it can communicate with services and other standalone containers that are also attached to the network.

networks:
  mynet1:
    driver: overlay
    attachable: true

driver

driver specifies which driver should be used for this network. Compose returns an error if the driver is not available on the platform.

networks:
  db-data:
    driver: bridge

For more information on drivers and available options, see Network drivers.

driver_opts

driver_opts specifies a list of options as key-value pairs to pass to the driver. These options are driver-dependent.

networks:
  frontend:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"

Consult the network drivers documentation for more information.

enable_ipv4

{{< summary-bar feature_name="Compose enable ipv4" >}}

enable_ipv4 can be used to disable IPv4 address assignment.

  networks:
    ip6net:
      enable_ipv4: false
      enable_ipv6: true

enable_ipv6

enable_ipv6 enables IPv6 address assignment.

  networks:
    ip6net:
      enable_ipv6: true

external

If set to true:

• external specifies that this network’s lifecycle is maintained outside of that of the application. Compose doesn't attempt to create these networks, and returns an error if one doesn't exist.
• All other attributes apart from name are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid.

In the following example, proxy is the gateway to the outside world. Instead of attempting to create a network, Compose queries the platform for an existing network called outside and connects the proxy service's containers to it.

services:
  proxy:
    image: example/proxy
    networks:
      - outside
      - default
  app:
    image: example/app
    networks:
      - default

networks:
  outside:
    external: true

ipam

ipam specifies a custom IPAM configuration. This is an object with several properties, each of which is optional:

• driver: Custom IPAM driver, instead of the default.
• config: A list with zero or more configuration elements, each containing a:
  • subnet: Subnet in CIDR format that represents a network segment
  • ip_range: Range of IPs from which to allocate container IPs
  • gateway: IPv4 or IPv6 gateway for the master subnet
  • aux_addresses: Auxiliary IPv4 or IPv6 addresses used by Network driver, as a mapping from hostname to IP
• options: Driver-specific options as a key-value mapping.

networks:
  mynet1:
    ipam:
      driver: default
      config:
        - subnet: 172.28.0.0/16
          ip_range: 172.28.5.0/24
          gateway: 172.28.5.254
          aux_addresses:
            host1: 172.28.1.5
            host2: 172.28.1.6
            host3: 172.28.1.7
      options:
        foo: bar
        baz: "0"

internal

By default, Compose provides external connectivity to networks. internal, when set to true, lets you create an externally isolated network.

labels

Add metadata to containers using labels. You can use either an array or a dictionary.

It is recommended that you use reverse-DNS notation to prevent labels from conflicting with those used by other software.

networks:
  mynet1:
    labels:
      com.example.description: "Financial transaction network"
      com.example.department: "Finance"
      com.example.label-with-empty-value: ""

networks:
  mynet1:
    labels:
      - "com.example.description=Financial transaction network"
      - "com.example.department=Finance"
      - "com.example.label-with-empty-value"

Compose sets com.docker.compose.project and com.docker.compose.network labels.

name

name sets a custom name for the network. The name field can be used to reference networks which contain special characters. The name is used as is and is not scoped with the project name.

networks:
  network1:
    name: my-app-net

It can also be used in conjunction with the external property to define the platform network that Compose should retrieve, typically by using a parameter so the Compose file doesn't need to hard-code runtime specific values:

networks:
  network1:
    external: true
    name: "${NETWORK_ID}"

Additional resources

For more examples, see Networking in Compose.