9.2.3.3 Compose External Volumes

Compose external volumes reference a volume that already exists outside the current Compose file's management, rather than having Compose create it, mirroring how an external network reference works, and useful for sharing persistent data across multiple, independently managed Compose projects.

Declaring an External Volume

The external option tells Compose this volume already exists and should be used as-is, without Compose attempting to create or remove it as part of this application's lifecycle.

services:
  api:
    volumes:
      - shared-data:/app/data

volumes:
  shared-data:
    external: true

Compose expects shared-data to already exist; docker compose down -v will not attempt to remove it, since it's understood to be managed outside this particular Compose file's scope.

Why External Volumes Support Cross-Project Data Sharing

Two separate Compose applications, each defined by their own independent Compose file, can both reference the same pre-existing external volume, enabling shared access to common data across otherwise unrelated projects.

docker volume create shared-uploads

volumes:
  shared-data:
    external: true
    name: shared-uploads

Both projects' Compose files reference this same manually created volume by its actual name, allowing data sharing between them.

Why External Volumes Protect Against Accidental Removal

Since Compose understands an external volume to be owned outside the current file's scope, it correctly avoids removing it during normal teardown operations, protecting data that other projects or processes might still depend on.

docker compose down -v
docker volume ls

The external volume remains present after this command, since Compose never considered itself responsible for its lifecycle.

Why Compose External Volumes Matter

External volume references allow a Compose application to participate in broader, shared persistent storage without inadvertently taking on responsibility for managing that storage's lifecycle, which properly belongs to whatever context actually created and owns it.