Using profiles with Compose

Profiles help you adjust your Compose application for different environments or use cases by selectively activating services. Services can be assigned to one or more profiles; unassigned services start by default, while assigned ones only start when their profile is active. This setup means specific services, like those for debugging or development, to be included in a singlecompose.ymlfile and activated only as needed.

Assigning profiles to services

Services are associated with profiles through the profilesattributewhich takes an array of profile names:

services:
frontend:
image:frontend
profiles:[frontend]

phpmyadmin:
image:phpmyadmin
depends_on:[db]
profiles:[debug]

backend:
image:backend

db:
image:mysql

Here the servicesfrontendandphpmyadminare assigned to the profiles frontendanddebugrespectively and as such are only started when their respective profiles are enabled.

Services without aprofilesattribute are always enabled. In this case runningdocker compose upwould only startbackendanddb.

Valid profiles names follow the regex format of[a-zA-Z0-9][a-zA-Z0-9_.-]+.

Tip

The core services of your application shouldn't be assignedprofilesso they are always enabled and automatically started.

Start specific profiles

To start a specific profile supply the--profile command-line optionor use the COMPOSE_PROFILESenvironment variable:

$docker compose --profile debug up

$COMPOSE_PROFILES=debug docker compose up

Both commands start the services with thedebugprofile enabled. In the previouscompose.ymlfile, this starts the services dbandphpmyadmin.

Start multiple profiles

You can also enable multiple profiles, e.g. withdocker compose --profile frontend --profile debug up the profilesfrontendanddebugwill be enabled.

Multiple profiles can be specified by passing multiple--profileflags or a comma-separated list for theCOMPOSE_PROFILESenvironment variable:

$docker compose --profile frontend --profile debug up

$COMPOSE_PROFILES=frontend,debug docker compose up

If you want to enable all profiles at the same time, you can rundocker compose --profile "*".

Auto-starting profiles and dependency resolution

When a service with assignedprofilesis explicitly targeted on the command line its profiles are started automatically so you don't need to start them manually. This can be used for one-off services and debugging tools. As an example consider the following configuration:

services:
backend:
image:backend

db:
image:mysql

db-migrations:
image:backend
command:myapp migrate
depends_on:
-db
profiles:
-tools

# Only start backend and db
$ docker compose up -d

# This runs db-migrations (and,if necessary, start db)
# by implicitly enabling the profiles `tools`
$ docker compose run db-migrations

But keep in mind thatdocker composeonly automatically starts the profiles of the services on the command line and not of any dependencies.

This means that any other services the targeted servicedepends_onshould either:

• Share a common profile
• Always be started, by omittingprofilesor having a matching profile started explicitly

services:
web:
image:web

mock-backend:
image:backend
profiles:["dev"]
depends_on:
-db

db:
image:mysql
profiles:["dev"]

phpmyadmin:
image:phpmyadmin
profiles:["debug"]
depends_on:
-db

# Only start "web"
$ docker compose up -d

# Start mock-backend (and, if necessary, db)
# by implicitly enabling profiles `dev`
$ docker compose up -d mock-backend

# This fails because profiles "dev" is not enabled
$ docker compose up phpmyadmin

Although targetingphpmyadminautomatically starts the profilesdebug,it doesn't automatically start the profiles required bydbwhich isdev.

To fix this you either have to add thedebugprofile to thedbservice:

db:
image:mysql
profiles:["debug","dev"]

or start thedevprofile explicitly:

#Profiles"debug"is started automatically by targeting phpmyadmin
$docker compose --profile dev up phpmyadmin
$COMPOSE_PROFILES=dev docker compose up phpmyadmin

Stop specific profiles

As with starting specific profiles, you can use the--profile command-line optionor use the COMPOSE_PROFILESenvironment variable:

$docker compose --profile debug down

$COMPOSE_PROFILES=debug docker compose down

Both commands stop and remove services with thedebugprofile. In the followingcompose.ymlfile, this stops the servicesdbandphpmyadmin.

services:
frontend:
image:frontend
profiles:[frontend]

phpmyadmin:
image:phpmyadmin
depends_on:[db]
profiles:[debug]

backend:
image:backend

db:
image:mysql

Note

Runningdocker compose downonly stopsbackendanddb.

Reference information

profiles