Docker Compose: Reuse Existing Volumes with external: true

Have you ever deployed a Docker Compose project, only to discover that it created a new volume instead of reusing your existing data?

The solution is simple: external: true.

Why does it happen?

Consider this configuration:

services:
  app:
    image: nginx:alpine
    volumes:
      - app-data:/usr/share/nginx/html

volumes:
  app-data:

By default, Docker Compose manages named volumes as project resources. Depending on the project name, it may create website_app-data instead of using your existing app-data volume.

Your container starts, but the expected data is missing.

The solution

Declare the volume as external:

volumes:
  app-data:
    external: true

Now Compose uses the existing Docker volume named app-data rather than creating a project-managed replacement.

Key points:

• No automatic creation: The volume must already exist.
• No project-name prefix: Compose uses the specified external volume name.
• Independent lifecycle: Compose does not manage the volume as its own resource.

If the volume doesn't exist, Compose reports an error.

Verify your configuration

Create the volume if necessary:

docker volume create app-data
docker volume inspect app-data
docker compose up -d

If the existing volume has a different name, specify it explicitly:

volumes:
  app-data:
    external: true
    name: legacy_website_data

This allows Compose to reference legacy_website_data through the logical key app-data.

Common mistake

Using name alone is not equivalent to external: true. The name property specifies the actual volume name; external: true declares that the volume already exists and is managed outside the current Compose project.

Remember: external volumes are not backups. They can still be deleted manually or lost through storage failure.

Conclusion

When you need Docker Compose to reuse an existing named volume, use:

volumes:
  app-data:
    external: true

One small configuration change can prevent unexpected volume duplication and help preserve data continuity across deployments.