You can reuse and modularize Docker Compose configurations by including other Compose files. This is useful if:

• You want to reuse other Compose files.
• You need to factor out parts of your application model into separate Compose files so they can be managed separately or shared with others.
• Teams need to maintain a Compose file with only necessary complexity for the limited amount of resources it has to declare for its own sub-domain within a larger deployment.

Theinclude top-level section is used to define the dependency on another Compose application, or sub-domain.Each path listed in theinclude section is loaded as an individual Compose application model, with its own project directory, in order to resolve relative paths.

Once the included Compose application is loaded, all resource definitions are copied into thecurrent Compose application model. Compose displays a warning if resource names conflict and doesn'ttry to merge them. To enforce this,include is evaluated after the Compose file(s) selectedto define the Compose application model have been parsed and merged, so that conflictsbetween Compose files are detected.

include applies recursively so an included Compose file which declares its owninclude section triggers those other files to be included as well.

Any volumes, networks, or other resources pulled in from the included Compose file can be used by the current Compose application for cross-service references. For example:

include:-my-compose-include.yaml#with serviceB declaredservices:serviceA:build:.depends_on:-serviceB#use serviceB directly as if it was declared in this Compose file

Compose also supports the use of interpolated variables withinclude. It's recommended that youspecify mandatory variables. For example:

include:  -${INCLUDE_PATH:?FOO}/compose.yaml

Short syntax

The short syntax only defines paths to other Compose files. The file is loaded with the parentfolder as the project directory, and an optional.env file that is loaded to define any variables' default valuesby interpolation. The local project's environment can override those values.

include:-../commons/compose.yaml-../another_domain/compose.yamlservices:webapp:depends_on:-included-service# defined by another_domain

In the previous example, both../commons/compose.yaml and../another_domain/compose.yaml are loaded as individual Compose projects. Relative pathsin Compose files being referred byinclude are resolved relative to their own Composefile path, not based on the local project's directory. Variables are interpolated using values set in the optional.env file in same folder and are overridden by the local project's environment.

Long syntax

The long syntax offers more control over the sub-project parsing:

include:-path:../commons/compose.yamlproject_directory:..env_file:../another/.env

path

path is required and defines the location of the Compose file(s) to be parsed and included into thelocal Compose model.

path can be set as:

• A string: When using a single Compose file.
• A list of strings: When multiple Compose files need to bemerged together to define the Compose model for the local application.

include:-path:-../commons/compose.yaml-./commons-override.yaml

project_directory

project_directory defines a base path to resolve relative paths set in the Compose file. It defaults tothe directory of the included Compose file.

env_file

env_file defines an environment file(s) to use to define default values when interpolating variablesin the Compose file being parsed. It defaults to.env file in theproject_directory for the Composefile being parsed.

env_file can be set to either a string or a list of strings when multiple environment files need to be mergedto define a project environment.

include:-path:../another/compose.yamlenv_file:-../another/.env-../another/dev.env

The local project's environment has precedence over the values set by the Compose file, so that the local project canoverride values for customization.

Additional resources

For more information on usinginclude, seeWorking with multiple Compose files