17.3.1.4 Explicit Compose Volumes

Explicit Compose volumes means naming and declaring every volume a stack uses in its top-level volumes section, turning the file into a complete, visible inventory of exactly what persistent data the stack manages, rather than allowing any service to silently create an anonymous, unnamed volume that exists outside of that inventory entirely.

The top-level volumes section as a data inventory

Declaring every volume explicitly in the top-level section, even when a service's own volume reference could technically create one implicitly, makes the Compose file itself a complete, accurate record of every piece of persistent state the stack is responsible for:

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

volumes:
  pgdata:

This explicit top-level declaration, paired with the service-level reference, is functionally similar to letting Compose infer the volume implicitly, but the explicit declaration makes it directly visible in one place, the volumes section, what persistent data the entire stack actually depends on, without needing to scan through every individual service definition to reconstruct that same inventory.

Avoiding anonymous volumes entirely in stack definitions

Every volume mount in a stack's definition should reference a named volume, never an anonymous one created implicitly through a bare container path with no source, since an anonymous volume has no memorable name, does not appear meaningfully in the top-level inventory, and is considerably easier to lose track of over the stack's lifetime:

services:
  api:
    volumes:
      - /app/node_modules

services:
  api:
    volumes:
      - node_modules_cache:/app/node_modules

volumes:
  node_modules_cache:

The second version names the volume explicitly even for what might otherwise be a quick, anonymous development convenience mount, keeping it visible in the inventory and consistent with every other volume the stack manages, rather than treating this one case as a special exception.

Labeling volumes with ownership and purpose metadata

Applying labels directly to volume declarations records ownership, purpose, and backup requirements as metadata attached to the volume itself, which remains discoverable later even if the original Compose file context is no longer immediately at hand:

volumes:
  pgdata:
    labels:
      - "project=my-api"
      - "purpose=primary-database"
      - "backup=required"

docker volume ls --filter "label=backup=required"

This metadata becomes directly queryable through docker volume inspect or filtered docker volume ls commands, providing a durable, discoverable record of which volumes specifically require backup attention, considerably more useful during operational review than relying entirely on tribal knowledge or separate, easily outdated documentation.

External volumes for data that outlives the stack

For data that should persist even if the entire stack is torn down and redefined, marking the volume as external explicitly documents this intent directly in the file, removing any ambiguity about whether a routine compose down -v is safe to run against this specific stack:

docker volume create pgdata

volumes:
  pgdata:
    external: true

This explicit marking is both a functional safeguard, since Compose will not remove an external volume even when instructed to remove volumes generally, and a clear, self-documenting statement that this particular volume's lifecycle is intentionally independent of the stack's own.

Distinguishing volumes by actual lifecycle intent

Not every volume in a stack needs the same lifecycle treatment; some genuinely should be discarded along with the stack (a build cache, a temporary working directory), while others should never be discarded casually (a primary database's data); making this distinction explicit through the external flag and accompanying labels, rather than treating every volume identically, reflects the actual, differentiated risk each one carries:

volumes:
  build-cache:
    # ephemeral, safe to discard with the stack
  pgdata:
    external: true
    # primary data store, must survive stack teardown

Documenting the data inventory for operational handoff

For a stack maintained by more than one person or team over time, the explicit, labeled volume inventory serves as direct, practical documentation for anyone needing to understand what data exists, where it lives, and how critical it is, without needing separate, easily outdated documentation maintained somewhere else entirely:

docker compose config | grep -A5 "^volumes:"

Reviewing this section directly is a fast, accurate way for anyone new to the project, or returning to it after time away, to understand exactly what persistent state the stack is responsible for and how seriously each piece of it should be treated.

Common mistakes

• Allowing services to create anonymous volumes implicitly rather than declaring every volume explicitly, named, in the top-level inventory.
• Not labeling volumes with ownership, purpose, or backup requirement metadata, leaving that information to exist only as informal, easily lost tribal knowledge.
• Treating every volume in a stack identically rather than explicitly distinguishing genuinely ephemeral ones from those holding data that must survive a stack teardown.
• Not marking volumes intended to outlive the stack as external, leaving them vulnerable to accidental removal through a routine compose down -v.
• Relying on separate, easily outdated documentation to record what persistent data a stack manages, rather than treating the Compose file's own explicit volume declarations as that documentation directly.

Explicit Compose volumes turn the top-level volumes section into a complete, accurate, and labeled inventory of every piece of persistent state a stack manages, which both prevents the anonymous volume confusion covered elsewhere and serves as direct, durable documentation of data ownership and lifecycle intent that does not depend on separate, easily outdated records maintained somewhere else.