Pre-defined environment variables (original) (raw)

Compose already comes with pre-defined environment variables. It also inherits common Docker CLI environment variables, such as DOCKER_HOST and DOCKER_CONTEXT. SeeDocker CLI environment variable reference for details.

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

• COMPOSE_PROJECT_NAME
• COMPOSE_FILE
• COMPOSE_PROFILES
• COMPOSE_CONVERT_WINDOWS_PATHS
• COMPOSE_PATH_SEPARATOR
• COMPOSE_IGNORE_ORPHANS
• COMPOSE_REMOVE_ORPHANS
• COMPOSE_PARALLEL_LIMIT
• COMPOSE_ANSI
• COMPOSE_STATUS_STDOUT
• COMPOSE_ENV_FILES
• COMPOSE_MENU
• COMPOSE_EXPERIMENTAL

You can set or change the pre-defined environment variables:

• With an.env file located in your working directory
• From the command line
• From yourshell

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

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 thebasename of the project directory or current directory violates this constraint, you must use one of the other mechanisms.

See also thecommand-line options overview andusing -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 in the current directory and, if not found, then Compose searches each parent directory recursively until a file by that name is found.
• When specifying multiple Compose files, the path separators are, by default, on:
  • Mac and Linux: : (colon)
  • Windows: ; (semicolon) For example:
    The path separator can also be customized usingCOMPOSE_PATH_SEPARATOR.

See also thecommand-line options overview andusing -f to specify name and path of one or more Compose files.

COMPOSE_PROFILES

Specifies one or more profiles to be enabled when docker compose up is run.

Services with matching profiles are started as well as any services for which no profile has been defined.

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

If specifying multiple profiles, use a comma as a separator.

The following example enables all services matching both the frontend and debug profiles and services without a profile.

See alsoUsing 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_REMOVE_ORPHANS

When enabled, Compose automatically removes orphaned containers when updating a service or stack. Orphaned containers are those that were created by a previous configuration but are no longer defined in the current compose.yaml file.

• Supported values:
  • true or 1, to enable automatic removal of orphaned containers
  • false or 0, to disable automatic removal. Compose displays a warning about orphaned containers instead.
• Defaults to: 0

COMPOSE_PARALLEL_LIMIT

Specifies the maximum level of parallelism for concurrent engine calls.

COMPOSE_ANSI

Specifies when to print ANSI control characters.

• Supported values:
  • auto, Compose detects if TTY mode can be used. Otherwise, use plain text mode
  • never, use plain text mode
  • always or 0, use TTY mode
• Defaults to: auto

COMPOSE_STATUS_STDOUT

When enabled, Compose writes its internal status and progress messages to stdout instead of stderr. The default value is false to clearly separate the output streams between Compose messages and your container's logs.

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

COMPOSE_ENV_FILES

Lets you specify which environment files Compose should use if --env-file isn't used.

When using multiple environment files, use a comma as a separator. For example:

If COMPOSE_ENV_FILES is not set, and you don't provide --env-file in the CLI, Docker Compose uses the default behavior, which is to look for an .env file in the project directory.

Requires: Docker Compose2.26.0 and later

When enabled, Compose displays a navigation menu where you can choose to open the Compose stack in Docker Desktop, switch onwatch mode, or useDocker Debug.

• Supported values:
  • true or 1, to enable
  • false or 0, to disable
• Defaults to: 1 if you obtained Docker Compose through Docker Desktop, otherwise the default is 0

COMPOSE_EXPERIMENTAL

Requires: Docker Compose2.26.0 and later

This is an opt-out variable. When turned off it deactivates the experimental features such as the navigation menu orSynchronized file shares.

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

The following environment variables have no effect in Compose V2. For more information, seeMigrate to Compose V2.

• COMPOSE_API_VERSIONBy default the API version is negotiated with the server. Use DOCKER_API_VERSION.
  See theDocker CLI environment variable reference page.
• COMPOSE_HTTP_TIMEOUT
• COMPOSE_TLS_VERSION
• COMPOSE_FORCE_WINDOWS_HOST
• COMPOSE_INTERACTIVE_NO_CLI
• COMPOSE_DOCKER_CLI_BUILDUse 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.