Extend your Compose file
extends attribute lets you share common configurations
among different files, or even different projects entirely.
is useful if you have several services that reuse a common set of configuration
extends you can define a common set of service options in one
place and refer to it from anywhere. You can refer to another Compose file and select a service you want to also use in your own application, with the ability to override some attributes for your own needs.
When you use multiple Compose files, you must make sure all paths in the files are relative to the base Compose file. This is required because extend files need not be valid Compose files. Extend files can contain small fragments of configuration. Tracking which fragment of a service is relative to which path is difficult and confusing, so to keep paths easier to understand, all paths must be defined relative to the base file.
When defining any service in your
compose.yaml file, you can declare that you are
extending another service:
services: web: extends: file: common-services.yml service: webapp
This instructs Compose to re-use the configuration for the
defined in the
common-services.yaml file. Suppose that
looks like this:
services: webapp: build: . ports: - "8000:8000" volumes: - "/data"
In this case, you get exactly the same result as if you wrote
docker-compose.yml with the same
values defined directly under
You can go further and define, or re-define, configuration locally in
services: web: extends: file: common-services.yml service: webapp environment: - DEBUG=1 cpu_shares: 5 important_web: extends: web cpu_shares: 10
You can also write other services and link your
web service to them:
services: web: extends: file: common-services.yml service: webapp environment: - DEBUG=1 cpu_shares: 5 depends_on: - db db: image: postgres
Extending an individual service is useful when you have multiple services that have a common configuration. The example below is a Compose app with two services, a web application and a queue worker. Both services use the same codebase and share many configuration options.
common.yaml file defines the common configuration:
services: app: build: . environment: CONFIG_FILE_PATH: /code/config API_KEY: xxxyyy cpu_shares: 5
docker-compose.yaml defines the concrete services which use the
services: webapp: extends: file: common.yaml service: app command: /code/run_web_app ports: - 8080:8080 depends_on: - queue - db queue_worker: extends: file: common.yaml service: app command: /code/run_worker depends_on: - queue
Another common use case for
extends is running one off or administrative tasks against one
or more services in a Compose app. This example demonstrates running a
docker-compose.yml defines the base configuration.
services: web: image: example/my_web_app:latest depends_on: db db: image: postgres:latest
docker-compose.admin.yml adds a new service to run the database
export or backup.
services: dbadmin: build: database_admin/ depends_on: - db
To start a normal environment, run
docker compose up -d. To run a database
backup, include the
docker-compose.admin.yml as well.
$ docker compose -f docker-compose.yml -f docker-compose.admin.yml \ run dbadmin db-backup
Compose extends files in the order they're specified on the command line.
depends_on are never shared between
extends. These exceptions exist to avoid implicit
dependencies; you always define
volumes_from locally. This ensures
dependencies between services are clearly visible when reading the current file.
Defining these locally also ensures that changes to the referenced file don't
extends is useful if you only need a single service to be shared and you are familiar with the file you're extending to, so you can to tweak the configuration. But this isn’t an acceptable solution when you want to re-use someone else's unfamiliar configurations and you don’t know about its own dependencies.