Change pre-defined environment variables

Important

From the end of June 2023 Compose V1 won’t be supported anymore and will be removed from all Docker Desktop versions.

Make sure you switch to Compose V2 with the docker compose CLI plugin or by activating the Use Docker Compose V2 setting in Docker Desktop. For more information, see the Evolution of Compose

Compose already comes with pre-defined environment variables.

This page contains information on how you can change the following pre-defined environment variables if you need to:

  • COMPOSE_CONVERT_WINDOWS_PATHS
  • COMPOSE_FILE
  • COMPOSE_PROFILES
  • COMPOSE_PROJECT_NAME
  • DOCKER_CERT_PATH
  • COMPOSE_PARALLEL_LIMIT
  • COMPOSE_IGNORE_ORPHANS
  • COMPOSE_REMOVE_ORPHANS
  • COMPOSE_PATH_SEPARATOR

Compose also inherits common Docker CLI environment variables, such as DOCKER_HOST and DOCKER_CONTEXT. See Docker CLI environment variable reference for details.

Methods to override

You can change the pre-defined environment variables:

When changing or setting any environment variables, be aware of Environment variable precedence.

Configure

COMPOSE_PROJECT_NAME

Sets the project name. This value is prepended along with the service name to the container’s name on startup.

For example, if your project name is myapp and it includes two services db and web, then Compose starts containers named myapp-db-1 and myapp-web-1 respectively.

Compose can set the project name in different ways. The level of precedence (from highest to lowest) for each method is as follows:

  1. The -p command line flag
  2. COMPOSE_PROJECT_NAME
  3. The top level name: variable from the config file (or the last name: from a series of config files specified using -f)
  4. The basename of the project directory containing the config file (or containing the first config file specified using -f)
  5. The basename of the current directory if no config file is specified

Project names must contain only lowercase letters, decimal digits, dashes, and underscores, and must begin with a lowercase letter or decimal digit. If the basename of the project directory or current directory violates this constraint, you must use one of the other mechanisms.

See also the command-line options overview and using -p to specify a project name.

COMPOSE_FILE

Specifies the path to a Compose file. Specifying multiple Compose files is supported.

  • Default behavior: If not provided, Compose looks for a file named compose.yaml or docker-compose.yaml in the current directory and, if not found, then Compose searches each parent directory recursively until a file by that name is found.
  • Default separator: When specifying multiple Compose files, the path separators are, by default, on:
    • Mac and Linux: : (colon),
    • Windows: ; (semicolon).

The path separator can also be customized using COMPOSE_PATH_SEPARATOR.

Example: COMPOSE_FILE=docker-compose.yml:docker-compose.prod.yml.

See also the command-line options overview and using -f to specify name and path of one or more Compose files.

COMPOSE_PROFILES

Specifies one or more profiles to be enabled on compose up execution. Services with matching profiles are started as well as any services for which no profile has been defined.

For example, calling docker compose upwith COMPOSE_PROFILES=frontend selects services with the frontend profile as well as any services without a profile specified.

  • Default separator: specify a list of profiles using a comma as separator.

Example: COMPOSE_PROFILES=frontend,debug
This example enables all services matching both the frontend and debug profiles and services without a profile.

See also Using profiles with Compose and the --profile command-line option.

COMPOSE_CONVERT_WINDOWS_PATHS

When enabled, Compose performs path conversion from Windows-style to Unix-style in volume definitions.

  • Supported values:
    • true or 1, to enable,
    • false or 0, to disable.
  • Defaults to: 0.

COMPOSE_PATH_SEPARATOR

Specifies a different path separator for items listed in COMPOSE_FILE.

  • Defaults to:
    • On MacOS and Linux to :,
    • On Windows to;.

COMPOSE_IGNORE_ORPHANS

When enabled, Compose doesn’t try to detect orphaned containers for the project.

  • Supported values:
    • true or 1, to enable,
    • false or 0, to disable.
  • Defaults to: 0.

COMPOSE_PARALLEL_LIMIT

Specifies the maximum level of parallelism for concurrent engine calls.

Deprecated in Compose v2

The pre-definded environment variables listed below are deprecated in V2.

  • COMPOSE_API_VERSION By default the API version is negotiated with the server. Use DOCKER_API_VERSION.
    See the Docker CLI environment variable reference page.
  • COMPOSE_HTTP_TIMEOUT
  • COMPOSE_TLS_VERSION
  • COMPOSE_FORCE_WINDOWS_HOST
  • COMPOSE_INTERACTIVE_NO_CLI
  • COMPOSE_DOCKER_CLI_BUILD Use DOCKER_BUILDKIT to select between BuildKit and the classic builder. If DOCKER_BUILDKIT=0 then docker compose build uses the classic builder to build images.