Using profiles with Compose
Compose V1 no longer receives updates and will not be available in new releases of Docker Desktop after June 2023.
Compose V2 is included with all currently supported versions of Docker Desktop. For more information, see Migrate to Compose V2.
Profiles help you adjust the Compose application model for various uses and environments by selectively enabling services. This is achieved by assigning each service to zero or more profiles. If unassigned, the service is always started but if assigned, it is only started if the profile is activated.
This allows you to define additional services in a single
that should only be started in specific scenarios, for example for debugging or
Assigning profiles to services
Services are associated with profiles through the
profiles attribute which 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 services
phpmyadmin are assigned to the profiles
debug respectively and as such are only started when their
respective profiles are enabled.
Services without a
profiles attribute are always enabled. In this
docker compose up would only start
Valid profiles names follow the regex format of
The core services of your application shouldn’t be assigned
profilesso they are always enabled and automatically started.
To enable profiles supply the
--profile command-line option or
COMPOSE_PROFILES environment variable:
$ docker compose --profile debug up
$ COMPOSE_PROFILES=debug docker compose up
The above commands would both start your application with the
debug profile enabled.
In the example,
docker-compose.yml file above, this starts the services
Enable multiple profiles
Multiple profiles can be specified by passing multiple
--profile flags or
a comma-separated list for the
COMPOSE_PROFILES environment variable:
$ docker compose --profile frontend --profile debug up
$ COMPOSE_PROFILES=frontend,debug docker compose up
Auto-enabling profiles and dependency resolution
When a service with assigned
profiles is explicitly targeted on the command
line its profiles are enabled automatically so you don’t need to enable 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 that
docker compose only automatically enables the
profiles of the services on the command line and not of any dependencies.
This means that any other services the targeted service
depends_on should either:
- Share a common profile
- Always be enabled, by omitting
profilesor having a matching profile enabled 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 disabled $ docker compose up phpmyadmin
phpmyadmin automatically enables the profiles
debug, it doesn’t automatically enable the profiles required by
db which is
To fix this you either have to add the
debug profile to the
db: image: mysql profiles: ["debug", "dev"]
or enable a profile of
# Profiles "debug" is enabled automatically by targeting phpmyadmin $ docker compose --profile dev up phpmyadmin $ COMPOSE_PROFILES=dev docker compose up phpmyadmin