Introduction

In Docker Compose, a named volume is defined in the top-level volumes section and then referenced from services. If you want to control the actual Docker volume name instead of accepting Compose's default project-prefixed name, use the name field.

The normal Compose pattern

A basic named volume looks like this:

1services:
2  db:
3    image: postgres:16
4    volumes:
5      - dbdata:/var/lib/postgresql/data
6
7volumes:
8  dbdata:

Here dbdata is the Compose-level volume key. By default, Docker Compose often creates a real Docker volume name by prefixing the project name, such as myproject_dbdata.

That default is useful because it prevents different Compose projects from accidentally colliding with each other's persistent storage.

How to give the volume an explicit name

If you want the actual Docker volume to have a specific global name, define name: under the volume.

1services:
2  db:
3    image: postgres:16
4    volumes:
5      - dbdata:/var/lib/postgresql/data
6
7volumes:
8  dbdata:
9    name: my-postgres-data

Now the service still refers to the volume as dbdata inside the Compose file, but Docker will create or use the volume named my-postgres-data.

That distinction matters. The Compose key and the real Docker volume name are related, but they are not the same thing.

When external matters

If the volume already exists and Compose should not try to create it, mark it as external.

1services:
2  app:
3    image: nginx:alpine
4    volumes:
5      - shareddata:/usr/share/nginx/html
6
7volumes:
8  shareddata:
9    external: true
10    name: company-shared-assets

This tells Compose to use an existing volume with that exact Docker name. That is useful when several projects or deployment steps intentionally share the same persistent data.

Project name and naming behavior

Compose also derives names from the project name, which can come from the directory name, the -p flag, or environment settings such as COMPOSE_PROJECT_NAME. If you do not set an explicit volume name, changing the project name changes the resulting volume name too.

That can be helpful for isolation and surprising for operators who expected a stable global name. Use name: only when you actually need that stability.

Named volumes versus bind mounts

Volume naming applies to Docker-managed named volumes, not to normal host bind mounts such as ./data:/app/data. A bind mount uses a filesystem path directly, so there is no Docker volume object to name in the same way.

That distinction helps explain why some Compose storage examples expose name: and others do not.

Why explicit names can be useful

A fixed volume name can simplify backup scripts, inspection commands, and cross-project sharing. The tradeoff is that global names reduce isolation, so they should be chosen deliberately rather than by habit in shared environments.

Common Pitfalls

• Assuming the top-level Compose volume key automatically becomes the real Docker volume name.
• Forgetting that Compose often prefixes names with the project name by default.
• Using name: without realizing services still reference the Compose key, not the raw Docker name.
• Marking a volume as external: true when it does not already exist.
• Forcing a global explicit volume name when project-scoped isolation would actually be safer.

Summary

• Declare named volumes in the top-level volumes section.
• Use name: when you want to control the actual Docker volume name.
• Without name:, Compose often prefixes the volume with the project name.
• Use external: true when the volume already exists and Compose should not manage its lifecycle.
• Keep the distinction clear between the Compose volume key and the real Docker volume name.