9.2.3.1 Compose Named Volumes

Compose named volumes are volumes declared under a Compose file's top-level volumes key with an explicit name, giving them the same identifiability and manageability benefits a manually created named volume would have outside of Compose, while keeping that declaration as part of the application's overall definition.

Naming Convention for Compose-Managed Volumes

A named volume declared in a Compose file is typically prefixed by Compose with the project name when actually created, producing a fully qualified name distinct from the short name used within the Compose file itself.

services:
  db:
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

docker volume ls

myapp_pgdata

The actual created volume's name combines the project name (myapp) with the short name used in the Compose file (pgdata), avoiding naming collisions between different Compose projects that might otherwise use the same short volume name.

Referencing the Volume Consistently Within the Compose File

Within the Compose file itself, the short name is what's used consistently to reference the volume, regardless of the fully qualified name Compose actually creates.

services:
  backup-tool:
    volumes:
      - pgdata:/data:ro

volumes:
  pgdata:

Overriding the Actual Created Name

The name option can override Compose's default naming convention, useful when a specific, predictable volume name is needed regardless of the project name.

volumes:
  pgdata:
    name: production-database-data

Why Compose Named Volumes Matter

Compose's named volume declaration provides the same explicit identifiability and manageability as a manually created named volume, while integrating cleanly into the same declarative, version-controlled application definition the rest of the Compose file provides.