9.2.2.4 Compose External Networks

Compose external networks reference a network that already exists outside the current Compose file's management, rather than having Compose create and manage that network itself, useful for connecting a Compose application to infrastructure that's shared across multiple, independently managed Compose projects.

Declaring an External Network

The external option tells Compose this network already exists and should simply be used as-is, rather than created or removed as part of this application's lifecycle.

services:
  api:
    networks:
      - shared-net

networks:
  shared-net:
    external: true

Compose expects shared-net to already exist; it will not attempt to create it, and docker compose down will not attempt to remove it either.

Why External Networks Are Useful for Cross-Project Connectivity

Two entirely separate Compose applications, each with their own independent Compose file, can both connect to the same pre-existing external network, enabling communication between services defined in otherwise unrelated projects.

docker network create shared-services-net

networks:
  shared-net:
    external: true
    name: shared-services-net

Both projects' Compose files can reference this same manually created network, allowing their respective services to communicate despite being defined and managed independently.

Why Compose Won't Manage an External Network's Lifecycle

Since an external network is explicitly understood to be created and owned outside the current Compose file, Compose correctly avoids creating or removing it, preventing one project's docker compose down from disrupting a network that other, independent projects might still depend on.

docker compose down
docker network ls

The external network remains present after this command, since Compose never considered itself responsible for its lifecycle in the first place.

Why Compose External Networks Matter

External network references provide a controlled way for an otherwise self-contained Compose application to participate in broader, shared network infrastructure, without inadvertently taking on responsibility for managing a network's lifecycle that genuinely belongs to a different, independent context.