Search or ask Docker

Container specification

Explore all the container attributes shared by services, jobs, and pre_start init containers.

View Markdown

A container specification defines the runtime configuration of a single container. It's the common set of attributes shared by anything that runs a container: services, jobs, and the init containers that pre_start declares.

Attributes that only apply to an orchestrated workload, such as build, ports, and healthcheck, aren't part of the container specification. The workload specification defines them.

Attributes

annotations

annotations defines annotations for the container. annotations can use either an array or a map.

annotations:
  com.example.foo: bar
annotations:
  - com.example.foo=bar

blkio_config

blkio_config defines a set of configuration options to set block I/O limits for a service.

services:
  foo:
    image: busybox
    blkio_config:
       weight: 300
       weight_device:
         - path: /dev/sda
           weight: 400
       device_read_bps:
         - path: /dev/sdb
           rate: '12mb'
       device_read_iops:
         - path: /dev/sdb
           rate: 120
       device_write_bps:
         - path: /dev/sdb
           rate: '1024k'
       device_write_iops:
         - path: /dev/sdb
           rate: 30

device_read_bps, device_write_bps

Set a limit in bytes per second for read / write operations on a given device. Each item in the list must have two keys:

  • path: Defines the symbolic path to the affected device.
  • rate: Either as an integer value representing the number of bytes or as a string expressing a byte value.

device_read_iops, device_write_iops

Set a limit in operations per second for read / write operations on a given device. Each item in the list must have two keys:

  • path: Defines the symbolic path to the affected device.
  • rate: As an integer value representing the permitted number of operations per second.

weight

Modify the proportion of bandwidth allocated to a service relative to other services. Takes an integer value between 10 and 1000, with 500 being the default.

weight_device

Fine-tune bandwidth allocation by device. Each item in the list must have two keys:

  • path: Defines the symbolic path to the affected device.
  • weight: An integer value between 10 and 1000.

cpu_count

cpu_count defines the number of usable CPUs for service container.

cpu_percent

cpu_percent defines the usable percentage of the available CPUs.

cpu_shares

cpu_shares defines, as integer value, a service container's relative CPU weight versus other containers.

cpu_period

cpu_period configures CPU CFS (Completely Fair Scheduler) period when a platform is based on Linux kernel.

cpu_quota

cpu_quota configures CPU CFS (Completely Fair Scheduler) quota when a platform is based on Linux kernel.

cpu_rt_runtime

cpu_rt_runtime configures CPU allocation parameters for platforms with support for real-time scheduler. It can be either an integer value using microseconds as unit or a duration.

 cpu_rt_runtime: '400ms'
 cpu_rt_runtime: '95000'

cpu_rt_period

cpu_rt_period configures CPU allocation parameters for platforms with support for real-time scheduler. It can be either an integer value using microseconds as unit or a duration.

 cpu_rt_period: '1400us'
 cpu_rt_period: '11000'

cpus

cpus define the number of (potentially virtual) CPUs to allocate to service containers. This is a fractional number. 0.000 means no limit.

When set, cpus must be consistent with the cpus attribute in the Deploy Specification.

cpuset

cpuset defines the explicit CPUs in which to permit execution. Can be a range 0-3 or a list 0,1

cap_add

cap_add specifies additional container capabilities as strings.

cap_add:
  - ALL

cap_drop

cap_drop specifies container capabilities to drop as strings.

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup

Requires: Docker Compose 2.15.0 and later

cgroup specifies the cgroup namespace to join. When unset, it is the container runtime's decision to select which cgroup namespace to use, if supported.

  • host: Runs the container in the Container runtime cgroup namespace.
  • private: Runs the container in its own private cgroup namespace.

cgroup_parent

cgroup_parent specifies an optional parent cgroup for the container.

cgroup_parent: m-executor-abcd

command

command overrides the default command declared by the container image, for example by Dockerfile's CMD.

command: bundle exec thin -p 3000

If the value is null, the default command from the image is used.

If the value is [] (empty list) or '' (empty string), the default command declared by the image is ignored, or in other words overridden to be empty.

Note

Unlike the CMD instruction in a Dockerfile, the command field doesn't automatically run within the context of the SHELL instruction defined in the image. If your command relies on shell-specific features, such as environment variable expansion, you need to explicitly run it within a shell. For example:

command: /bin/sh -c 'echo "hello $$HOSTNAME"'

The value can also be a list, similar to the exec-form syntax used by the Dockerfile.

configs

configs let services adapt their behaviour without the need to rebuild a Docker image. Services can only access configs when explicitly granted by the configs attribute. Two different syntax variants are supported.

Compose reports an error if config doesn't exist on the platform or isn't defined in the configs top-level element in the Compose file.

There are two syntaxes defined for configs: a short syntax and a long syntax.

You can grant a service access to multiple configs, and you can mix long and short syntax.

Short syntax

The short syntax variant only specifies the config name. This grants the container access to the config and mounts it as files into a service’s container’s filesystem. The location of the mount point within the container defaults to /<config_name> in Linux containers, and C:\<config-name> in Windows containers.

The following example uses the short syntax to grant the redis service access to the my_config and my_other_config configs. The value of my_config is set to the contents of the file ./my_config.txt, and my_other_config is defined as an external resource, which means that it has already been defined in the platform. If the external config does not exist, the deployment fails.

services:
  redis:
    image: redis:latest
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

Long syntax

The long syntax provides more granularity in how the config is created within the service's task containers.

  • source: The name of the config as it exists in the platform.
  • target: The path and name of the file to be mounted in the service's task containers. Defaults to /<source> if not specified.
  • uid and gid: The numeric uid or gid that owns the mounted config file within the service's task containers.
  • mode: The permissions for the file that is mounted within the service's task containers, in octal notation. Default value is world-readable (0444). Writable bit must be ignored. The executable bit can be set.

The following example sets the name of my_config to redis_config within the container, sets the mode to 0440 (group-readable) and sets the user and group to 103. The redis service does not have access to the my_other_config config.

services:
  redis:
    image: redis:latest
    configs:
      - source: my_config
        target: /redis_config
        uid: "103"
        gid: "103"
        mode: 0440
configs:
  my_config:
    external: true
  my_other_config:
    external: true

credential_spec

credential_spec configures the credential spec for a managed service account.

If you have services that use Windows containers, you can use file: and registry: protocols for credential_spec. Compose also supports additional protocols for custom use-cases.

The credential_spec must be in the format file://<filename> or registry://<value-name>.

credential_spec:
  file: my-credential-spec.json

When using registry:, the credential spec is read from the Windows registry on the daemon's host. A registry value with the given name must be located in:

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

The following example loads the credential spec from a value named my-credential-spec in the registry:

credential_spec:
  registry: my-credential-spec

Example gMSA configuration

When configuring a gMSA credential spec for a service, you only need to specify a credential spec with config, as shown in the following example:

services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

configs:
  my_credentials_spec:
    file: ./my-credential-spec.json

device_cgroup_rules

device_cgroup_rules defines a list of device cgroup rules for this container. The format is the same format the Linux kernel specifies in the Control Groups Device Whitelist Controller.

device_cgroup_rules:
  - 'c 1:3 mr'
  - 'a 7:* rmw'

devices

devices defines a list of device mappings for created containers in the form of HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS].

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm"

devices can also rely on the CDI syntax to let the container runtime select a device:

devices:
  - "vendor1.com/device=gpu"

dns

dns defines custom DNS servers to set on the container network interface configuration. It can be a single value or a list.

dns: 8.8.8.8
dns:
  - 8.8.8.8
  - 9.9.9.9

dns_opt

dns_opt list custom DNS options to be passed to the container’s DNS resolver (/etc/resolv.conf file on Linux).

dns_opt:
  - use-vc
  - no-tld-query

dns_search defines custom DNS search domains to set on container network interface configuration. It can be a single value or a list.

dns_search: example.com
dns_search:
  - dc1.example.com
  - dc2.example.com

domainname

domainname declares a custom domain name to use for the service container. It must be a valid RFC 1123 hostname.

driver_opts

Requires: Docker Compose 2.27.1 and later

driver_opts specifies a list of options as key-value pairs to pass to the driver. These options are driver-dependent.

services:
  app:
    networks:
      app_net:
        driver_opts:
          com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"

Consult the network drivers documentation for more information.

entrypoint

entrypoint declares the default entrypoint for the service container. This overrides the ENTRYPOINT instruction from the service's Dockerfile.

If entrypoint is non-null, Compose ignores any default command from the image, for example the CMD instruction in the Dockerfile.

See also command to set or override the default command to be executed by the entrypoint process.

In its short form, the value can be defined as a string:

entrypoint: /code/entrypoint.sh

Alternatively, the value can also be a list, in a manner similar to the Dockerfile:

entrypoint:
  - php
  - -d
  - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
  - -d
  - memory_limit=-1
  - vendor/bin/phpunit

If the value is null, the default entrypoint from the image is used.

If the value is [] (empty list) or '' (empty string), the default entrypoint declared by the image is ignored, or in other words, overridden to be empty.

env_file

The env_file attribute is used to specify one or more files that contain environment variables to be passed to the containers.

env_file: .env

Relative paths are resolved from the Compose file's parent folder. As absolute paths prevent the Compose file from being portable, Compose warns you when such a path is used to set env_file.

Environment variables declared in the environment section override these values. This holds true even if those values are empty or undefined.

env_file can also be a list. The files in the list are processed from the top down. For the same variable specified in two environment files, the value from the last file in the list stands.

env_file:
  - ./a.env
  - ./b.env

List elements can also be declared as a mapping, which then lets you set additional attributes.

required

Requires: Docker Compose 2.24.0 and later

The required attribute defaults to true. When required is set to false and the .env file is missing, Compose silently ignores the entry.

env_file:
  - path: ./default.env
    required: true # default
  - path: ./override.env
    required: false

format

Requires: Docker Compose 2.30.0 and later

The format attribute lets you use an alternative file format for the env_file. When not set, env_file is parsed according to the Compose rules outlined in Env_file format.

raw format lets you use an env_file with key=value items, but without any attempt from Compose to parse the value for interpolation. This let you pass values as-is, including quotes and $ signs.

env_file:
  - path: ./default.env
    format: raw

Env_file format

Each line in an .env file must be in VAR[=[VAL]] format. The following syntax rules apply:

  • Lines beginning with # are processed as comments and ignored.
  • Blank lines are ignored.
  • Unquoted and double-quoted (") values have Interpolation applied.
  • Each line represents a key-value pair. Values can optionally be quoted.
  • Delimiter separating key and value can be either = or :.
  • Spaces before and after value are ignored.
    • VAR=VAL -> VAL
    • VAR="VAL" -> VAL
    • VAR='VAL' -> VAL
    • VAR: VAL -> VAL
    • VAR = VAL -> VAL
  • Inline comments for unquoted values must be preceded with a space.
    • VAR=VAL # comment -> VAL
    • VAR=VAL# not a comment -> VAL# not a comment
  • Inline comments for quoted values must follow the closing quote.
    • VAR="VAL # not a comment" -> VAL # not a comment
    • VAR="VAL" # comment -> VAL
  • Single-quoted (') values are used literally.
    • VAR='$OTHER' -> $OTHER
    • VAR='${OTHER}' -> ${OTHER}
  • Quotes can be escaped with \.
    • VAR='Let\'s go!' -> Let's go!
    • VAR="{\"hello\": \"json\"}" -> {"hello": "json"}
  • Common shell escape sequences including \n, \r, \t, and \\ are supported in double-quoted values.
    • VAR="some\tvalue" -> some value
    • VAR='some\tvalue' -> some\tvalue
    • VAR=some\tvalue -> some\tvalue

VAL may be omitted, in such cases the variable value is an empty string. =VAL may be omitted, in such cases the variable is unset.

# Set Rails/Rack environment
RACK_ENV=development
VAR="quoted"

environment

The environment attribute defines environment variables set in the container. environment can use either an array or a map. Any boolean values; true, false, yes, no, should be enclosed in quotes to ensure they are not converted to True or False by the YAML parser.

Environment variables can be declared by a single key (no value to equals sign). In this case Compose relies on you to resolve the value. If the value is not resolved, the variable is unset and is removed from the service container environment.

Map syntax:

environment:
  RACK_ENV: development
  SHOW: "true"
  USER_INPUT:

Array syntax:

environment:
  - RACK_ENV=development
  - SHOW=true
  - USER_INPUT

When both env_file and environment are set for a service, values set by environment have precedence.

extra_hosts

extra_hosts adds hostname mappings to the container network interface configuration (/etc/hosts for Linux).

Short syntax

Short syntax uses plain strings in a list. Values must set hostname and IP address for additional hosts in the form of HOSTNAME=IP.

extra_hosts:
  - "somehost=162.242.195.82"
  - "otherhost=50.31.209.229"
  - "myhostv6=::1"

IPv6 addresses can be enclosed in square brackets, for example:

extra_hosts:
  - "myhostv6=[::1]"

The separator = is preferred, but : can also be used. Introduced in Docker Compose version 2.24.1. For example:

extra_hosts:
  - "somehost:162.242.195.82"
  - "myhostv6:::1"

Long syntax

Alternatively, extra_hosts can be set as a mapping between hostname(s) and IP(s)

extra_hosts:
  somehost: "162.242.195.82"
  otherhost: "50.31.209.229"
  myhostv6: "::1"

Compose creates a matching entry with the IP address and hostname in the container's network configuration, which means for Linux /etc/hosts get extra lines:

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

gpus

Requires: Docker Compose 2.30.0 and later

gpus specifies GPU devices to be allocated for container usage. This is equivalent to a device request with an implicit gpu capability.

services:
  model:
    gpus:
      - driver: 3dfx
        count: 2

gpus also can be set as string all to allocate all available GPU devices to the container.

services:
  model:
    gpus: all

group_add

group_add specifies additional groups, by name or number, which the user inside the container must be a member of.

An example of where this is useful is when multiple containers (running as different users) need to all read or write the same file on a shared volume. That file can be owned by a group shared by all the containers, and specified in group_add.

services:
  myservice:
    image: alpine
    group_add:
      - mail

Running id inside the created container must show that the user belongs to the mail group, which would not have been the case if group_add were not declared.

hostname

hostname declares a custom host name to use for the service container. It must be a valid RFC 1123 hostname.

image

image specifies the image to start the container from. image must follow the Open Container Specification addressable image format, as [<registry>/][<project>/]<image>[:<tag>|@<digest>].

    image: redis
    image: redis:5
    image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
    image: library/redis
    image: docker.io/library/redis
    image: my_private.registry:5000/redis

If the image does not exist on the platform, Compose attempts to pull it based on the pull_policy. If you are also using the Compose Build Specification, there are alternative options for controlling the precedence of pull over building the image from source, however pulling the image is the default behavior.

image may be omitted from a Compose file as long as a build section is declared. If you are not using the Compose Build Specification, Compose won't work if image is missing from the Compose file.

init

init runs an init process (PID 1) inside the container that forwards signals and reaps processes. Set this option to true to enable this feature for the service.

services:
  web:
    image: alpine:latest
    init: true

The init binary that is used is platform specific.

ipc

ipc configures the IPC isolation mode set by the service container.

  • shareable: Gives the container its own private IPC namespace, with a possibility to share it with other containers.
  • service:{name}: Makes the container join another container's (shareable) IPC namespace.
    ipc: "shareable"
    ipc: "service:[service name]"

isolation

isolation specifies a container’s isolation technology. Supported values are platform specific.

labels

labels add metadata to containers. You can use either an array or a map.

It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software.

labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""
labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

Compose creates containers with canonical labels:

  • com.docker.compose.project set on all resources created by Compose to the user project name
  • com.docker.compose.service set on service containers with service name as defined in the Compose file

The com.docker.compose label prefix is reserved. Specifying labels with this prefix in the Compose file results in a runtime error.

label_file

Requires: Docker Compose 2.32.2 and later

The label_file attribute lets you load labels for a service from an external file or a list of files. This provides a convenient way to manage multiple labels without cluttering the Compose file.

The file uses a key-value format, similar to env_file. You can specify multiple files as a list. When using multiple files, they are processed in the order they appear in the list. If the same label is defined in multiple files, the value from the last file in the list overrides earlier ones.

services:
  one:
    label_file: ./app.labels

  two:
    label_file:
      - ./app.labels
      - ./additional.labels

If a label is defined in both the label_file and the labels attribute, the value in labels takes precedence.

logging

logging defines the logging configuration for the service.

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

The driver name specifies a logging driver for the service's containers. The default and available values are platform specific. Driver specific options can be set with options as key-value pairs.

mac_address

Available with Docker Compose version 2.24.0 and later.

mac_address sets a Mac address for the service container.

Note

Container runtimes might reject this value, for example Docker Engine >= v25.0. In that case, you should use networks.mac_address instead.

mem_limit

mem_limit configures a limit on the amount of memory a container can allocate, set as a string expressing a byte value.

When set, mem_limit must be consistent with the limits.memory attribute in the Deploy Specification.

mem_reservation

mem_reservation configures a reservation on the amount of memory a container can allocate, set as a string expressing a byte value.

When set, mem_reservation must be consistent with the reservations.memory attribute in the Deploy Specification.

mem_swappiness

mem_swappiness defines as a percentage, a value between 0 and 100, for the host kernel to swap out anonymous memory pages used by a container.

  • 0: Turns off anonymous page swapping.
  • 100: Sets all anonymous pages as swappable.

The default value is platform specific.

memswap_limit

memswap_limit defines the amount of memory the container is allowed to swap to disk. This is a modifier attribute that only has meaning if memory is also set. Using swap lets the container write excess memory requirements to disk when the container has exhausted all the memory that is available to it. There is a performance penalty for applications that swap memory to disk often.

  • If memswap_limit is set to a positive integer, then both memory and memswap_limit must be set. memswap_limit represents the total amount of memory and swap that can be used, and memory controls the amount used by non-swap memory. So if memory="300m" and memswap_limit="1g", the container can use 300m of memory and 700m (1g - 300m) swap.
  • If memswap_limit is set to 0, the setting is ignored, and the value is treated as unset.
  • If memswap_limit is set to the same value as memory, and memory is set to a positive integer, the container does not have access to swap.
  • If memswap_limit is unset, and memory is set, the container can use as much swap as the memory setting, if the host has swap memory configured. For instance, if memory="300m" and memswap_limit is not set, the container can use 600m in total of memory and swap.
  • If memswap_limit is explicitly set to -1, the container is allowed to use unlimited swap, up to the amount available on the host system.

models

Requires: Docker Compose 2.38.0 and later

models defines which AI models the service should use at runtime. Each referenced model must be defined under the models top-level element.

services:
  short_syntax:
    image: app
    models:
      - my_model
  long_syntax:
    image: app
    models:
      my_model:
        endpoint_var: MODEL_URL
        model_var: MODEL

When a service is linked to a model, Docker Compose injects environment variables to pass connection details and model identifiers to the container. This allows the application to locate and communicate with the model dynamically at runtime, without hard-coding values.

Long syntax

The long syntax gives you more control over the environment variable names.

  • endpoint_var sets the name of the environment variable that holds the model runner’s URL.
  • model_var sets the name of the environment variable that holds the model identifier.

If either is omitted, Compose automatically generates the environment variable names based on the model key using the following rules:

  • Convert the model key to uppercase
  • Replace any '-' characters with '_'
  • Append _URL for the endpoint variable

network_mode

network_mode sets a service container's network mode.

  • bridge: Connects the container to Docker's default bridge network instead of a project-specific network. Containers on the default bridge network cannot resolve each other by service name . Instead, use a user-defined network for DNS resolution.
  • none: Turns off all container networking.
  • host: Gives the container raw access to the host's network interface.
  • service:{name}: Gives the container access to the specified container by referring to its service name.
  • container:{name}: Gives the container access to the specified container by referring to its container ID.

For more information container networks, see the Docker Engine documentation.

    network_mode: "bridge"
    network_mode: "host"
    network_mode: "none"
    network_mode: "service:[service name]"

When set, the networks attribute is not allowed and Compose rejects any Compose file containing both attributes.

networks

The networks attribute defines the networks that service containers are attached to, referencing entries under the networks top-level element. The networks attribute helps manage the networking aspects of containers, providing control over how services are segmented and interact within the Docker environment. This is used to specify which networks the containers for that service should connect to. This is important for defining how containers communicate with each other and externally.

services:
  some-service:
    networks:
      - some-network
      - other-network

For more information about the networks top-level element, see Networks.

Implicit default network

If networks is empty or absent from the Compose file, Compose considers an implicit definition for the service to be connected to the default network:

services:
  some-service:
    image: foo

This example is actually equivalent to:

services:
  some-service:
    image: foo
    networks:
      default: {}

If you want the service to not be connected a network, you must set network_mode: none.

aliases

aliases declares alternative hostnames for the service on the network. Other containers on the same network can use either the service name or an alias to connect to one of the service's containers.

Since aliases are network-scoped, the same service can have different aliases on different networks.

Note

A network-wide alias can be shared by multiple containers, and even by multiple services. If it is, then exactly which container the name resolves to is not guaranteed.

services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2

In the following example, service frontend is able to reach the backend service at the hostname backend or database on the back-tier network. The service monitoring is able to reach same backend service at backend or mysql on the admin network.

services:
  frontend:
    image: example/webapp
    networks:
      - front-tier
      - back-tier

  monitoring:
    image: example/monitoring
    networks:
      - admin

  backend:
    image: example/backend
    networks:
      back-tier:
        aliases:
          - database
      admin:
        aliases:
          - mysql

networks:
  front-tier: {}
  back-tier: {}
  admin: {}

use_service_name_alias

Requires: Docker Compose 5.7.0 and later

use_service_name_alias controls whether the service name is registered as an alias of the service's containers on the network. It defaults to true. It requires the long syntax of networks.

When set to false, the service name is not an alias on this network. The values listed in aliases are not affected, and neither are the other networks of the service.

You must distinguish an unset value from false, so that a Compose file merged on top of another can set the attribute back to true.

This is useful when a network is shared by several Compose applications that each define a service with the same name: the name would otherwise resolve to a container of any of them. Give each service a distinct alias instead:

networks:
  shared:
    external: true

services:
  database:
    networks:
      shared:
        aliases:
          - project1-database
        use_service_name_alias: false

If the service is attached to no other network where its name is registered, other services can no longer reach it by service name. Use aliases to give it a name on that network. links are not affected.

Note

use_service_name_alias only affects name resolution. It does not isolate the network. Containers attached to it can still reach the service by IP address or by any of its aliases.

interface_name

Requires: Docker Compose 2.36.0 and later

interface_name lets you specify the name of the network interface used to connect a service to a given network. This ensures consistent and predictable interface naming across services and networks.

services:
  backend:
    image: alpine
    command: ip link show
    networks:
      back-tier:
        interface_name: eth0

Running the example Compose application shows:

backend-1  | 11: eth0@if64: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP

ipv4_address, ipv6_address

Specify a static IP address for a service container when joining the network.

The corresponding network configuration in the top-level networks section must have an ipam attribute with subnet configurations covering each static address.

services:
  frontend:
    image: example/webapp
    networks:
      front-tier:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  front-tier:
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"
        - subnet: "2001:3984:3989::/64"

link_local_ips specifies a list of link-local IPs. Link-local IPs are special IPs which belong to a well known subnet and are purely managed by the operator, usually dependent on the architecture where they are deployed.

Example:

services:
  app:
    image: busybox
    command: top
    networks:
      app_net:
        link_local_ips:
          - 57.123.22.11
          - 57.123.22.13
networks:
  app_net:
    driver: bridge

mac_address

Requires: Docker Compose 2.23.2 and later

mac_address sets the Mac address used by the service container when connecting to this particular network.

driver_opts

driver_opts specifies a list of options as key-value pairs to pass to the driver. These options are driver-dependent. Consult the driver's documentation for more information.

services:
  app:
    networks:
      app_net:
        driver_opts:
          foo: "bar"
          baz: 1

gw_priority

Requires: Docker Compose 2.33.1 and later

The network with the highest gw_priority is selected as the default gateway for the service container. If unspecified, the default value is 0.

In the following example, app_net_2 will be selected as the default gateway.

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
      app_net_2:
        gw_priority: 1
      app_net_3:
networks:
  app_net_1:
  app_net_2:
  app_net_3:

priority

priority indicates in which order Compose connects the service’s containers to its networks. If unspecified, the default value is 0.

If the container runtime accepts a mac_address attribute at service level, it is applied to the network with the highest priority. In other cases, use attribute networks.mac_address.

priority does not affect which network is selected as the default gateway. Use the gw_priority attribute instead.

priority does not control the order in which networks connections are added to the container, it cannot be used to determine the device name (eth0 etc.) in the container.

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
        priority: 1000
      app_net_2:

      app_net_3:
        priority: 100
networks:
  app_net_1:
  app_net_2:
  app_net_3:

oom_kill_disable

If oom_kill_disable is set, Compose configures the platform so it won't kill the container in case of memory starvation.

oom_score_adj

oom_score_adj tunes the preference for containers to be killed by platform in case of memory starvation. Value must be within -1000,1000 range.

pid

pid sets the PID mode for container created by Compose. Supported values are platform specific.

pids_limit

pids_limit tunes a container’s PIDs limit. Set to -1 for unlimited PIDs.

pids_limit: 10

When set, pids_limit must be consistent with the pids attribute in the Deploy Specification.

platform

platform defines the target platform the containers for the service run on. It uses the os[/arch[/variant]] syntax.

The values of os, arch, and variant must conform to the convention used by the OCI Image Spec.

Compose uses this attribute to determine which version of the image is pulled and/or on which platform the service’s build is performed.

platform: darwin
platform: windows/amd64
platform: linux/arm64/v8

privileged

privileged configures the service container to run with elevated privileges. Support and actual impacts are platform specific.

pull_policy

pull_policy defines the decisions Compose makes when it starts to pull images. Possible values are:

  • always: Compose always pulls the image from the registry.
  • never: Compose doesn't pull the image from a registry and relies on the platform cached image. If there is no cached image, a failure is reported.
  • missing: Compose pulls the image only if it's not available in the platform cache. This is the default option if you are not also using the Compose Build Specification. if_not_present is considered an alias for this value for backward compatibility. The latest tag is always pulled even when the missing pull policy is used.
  • build: Compose builds the image. Compose rebuilds the image if it's already present.
  • daily: Compose checks the registry for image updates if the last pull took place more than 24 hours ago.
  • weekly: Compose checks the registry for image updates if the last pull took place more than 7 days ago.
  • every_<duration>: Compose checks the registry for image updates if the last pull took place before <duration>. Duration can be expressed in weeks (w), days (d), hours (h), minutes (m), seconds (s) or a combination of these.
services:
  test:
    image: nginx
    pull_policy: every_12h

read_only

read_only configures the service container to be created with a read-only filesystem.

runtime

runtime specifies which runtime to use for the service’s containers.

For example, runtime can be the name of an implementation of OCI Runtime Spec, such as "runc".

web:
  image: busybox:latest
  command: true
  runtime: runc

The default is runc. To use a different runtime, see Alternative runtimes.

secrets

The secrets attribute grants access to sensitive data defined by the secrets top-level element on a per-service basis. Services can be granted access to multiple secrets.

Two different syntax variants are supported; the short syntax and the long syntax. Long and short syntax for secrets may be used in the same Compose file.

Compose reports an error if the secret doesn't exist on the platform or isn't defined in the secrets top-level section of the Compose file.

Defining a secret in the top-level secrets must not imply granting any service access to it. Such grant must be explicit within service specification as secrets service element.

Short syntax

The short syntax variant only specifies the secret name. This grants the container access to the secret and mounts it as read-only to /run/secrets/<secret_name> within the container. The source name and destination mountpoint are both set to the secret name.

The following example uses the short syntax to grant the frontend service access to the server-certificate secret. The value of server-certificate is set to the contents of the file ./server.cert.

services:
  frontend:
    image: example/webapp
    secrets:
      - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

Long syntax

The long syntax provides more granularity in how the secret is created within the service's containers.

  • source: The name of the secret as it exists on the platform.
  • target: The name of the file to be mounted in /run/secrets/ in the service's task container, or absolute path of the file if an alternate location is required. Defaults to source if not specified.
  • uid and gid: The numeric uid or gid that owns the file within /run/secrets/ in the service's task containers.
  • mode: The permissions for the file to be mounted in /run/secrets/ in the service's task containers, in octal notation. The default value is world-readable permissions (mode 0444). The writable bit must be ignored if set. The executable bit may be set.

Note that support for uid, gid, and mode attributes are only implemented in Docker Compose when the source of the secret is environment. When the source is a file, Compose uses a bind-mount under the hood which doesn't allow uid remapping, and these attributes are silently ignored.

The following example sets the name of the my-token secret file within the container, sets the mode to 0440 (group-readable), and sets the user and group to 103. The value of my-token is read from the MY_TOKEN environment variable.

services:
  frontend:
    image: example/webapp
    secrets:
      - source: my-token
        uid: "103"
        gid: "103"
        mode: 0o440
secrets:
  my-token:
    environment: "MY_TOKEN"

security_opt

security_opt overrides the default labeling scheme for each container.

Options accept either option=value or option:value syntax. For boolean options such as no-new-privileges, the value may be omitted entirely, in which case the option is treated as enabled. The following syntaxes are all equivalent:

security_opt:
  - no-new-privileges
  - no-new-privileges=true
  - no-new-privileges:true
security_opt:
  - label=user:USER
  - label=role:ROLE

For further default labeling schemes you can override, see Security configuration.

shm_size

shm_size configures the size of the shared memory (/dev/shm partition on Linux) allowed by the service container. It's specified as a byte value.

stop_grace_period

stop_grace_period specifies how long Compose must wait when attempting to stop a container if it doesn't handle SIGTERM (or whichever stop signal has been specified with stop_signal), before sending SIGKILL. It's specified as a duration.

    stop_grace_period: 1s
    stop_grace_period: 1m30s

Default value is 10 seconds for the container to exit before sending SIGKILL.

stop_signal

stop_signal defines the signal that Compose uses to stop the service containers. If unset containers are stopped by Compose by sending SIGTERM.

stop_signal: SIGUSR1

storage_opt

storage_opt defines storage driver options for a service.

storage_opt:
  size: '1G'

sysctls

sysctls defines kernel parameters to set in the container. sysctls can use either an array or a map.

sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0
sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0

You can only use sysctls that are namespaced in the kernel. Docker does not support changing sysctls inside a container that also modify the host system. For an overview of supported sysctls, refer to configure namespaced kernel parameters (sysctls) at runtime.

tmpfs

tmpfs mounts a temporary file system inside the container. It can be a single value or a list.

tmpfs:
 - <path>
 - <path>:<options>
  • path: The path inside the container where the tmpfs will be mounted.
  • options: Comma-separated list of options for the tmpfs mount.

Available options:

  • mode: Sets the file system permissions.
  • uid: Sets the user ID that owns the mounted tmpfs.
  • gid: Sets the group ID that owns the mounted tmpfs.
services:
  app:
    tmpfs:
      - /data:mode=755,uid=1009,gid=1009
      - /run

ulimits

ulimits overrides the default ulimits for a container. It's specified either as an integer for a single limit or as mapping for soft/hard limits.

ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000

use_api_socket

When use_api_socket is set, the container is able to interact with the underlying container engine through the API socket. Your credentials are mounted inside the container so the container acts as a pure delegate for your commands relating to the container engine. Typically, commands ran by container can pull and push to your registry.

user

user overrides the user used to run the container process. The default is set by the image, for example Dockerfile USER. If it's not set, then root.

userns_mode

userns_mode sets the user namespace for the service. Supported values are platform specific and may depend on platform configuration.

userns_mode: "host"

uts

Requires: Docker Compose 2.15.1 and later

uts configures the UTS namespace mode set for the service container. When unspecified it is the runtime's decision to assign a UTS namespace, if supported. Available values are:

  • 'host': Results in the container using the same UTS namespace as the host.
    uts: "host"

volumes

The volumes attribute define mount host paths or named volumes that are accessible by service containers. You can use volumes to define multiple types of mounts; volume, bind, tmpfs, or npipe.

If the mount is a host path and is only used by a single service, it can be declared as part of the service definition. To reuse a volume across multiple services, a named volume must be declared in the volumes top-level element.

The following example shows a named volume (db-data) being used by the backend service, and a bind mount defined for a single service.

services:
  backend:
    image: example/backend
    volumes:
      - type: volume
        source: db-data
        target: /data
        volume:
          nocopy: true
          subpath: sub
      - type: bind
        source: /var/run/postgres/postgres.sock
        target: /var/run/postgres/postgres.sock

volumes:
  db-data:

For more information about the volumes top-level element, see Volumes.

Short syntax

The short syntax uses a single string with colon-separated values to specify a volume mount (VOLUME:CONTAINER_PATH), or an access mode (VOLUME:CONTAINER_PATH:ACCESS_MODE).

  • VOLUME: Can be either a host path on the platform hosting containers (bind mount) or a volume name.
  • CONTAINER_PATH: The path in the container where the volume is mounted.
  • ACCESS_MODE: A comma-separated , list of options:
    • rw: Read and write access. This is the default if none is specified.
    • ro: Read-only access.
    • z: SELinux option indicating that the bind mount host content is shared among multiple containers.
    • Z: SELinux option indicating that the bind mount host content is private and unshared for other containers.
Note

The SELinux re-labeling bind mount option is ignored on platforms without SELinux.

Note

Relative host paths are only supported by Compose that deploy to a local container runtime. This is because the relative path is resolved from the Compose file’s parent directory which is only applicable in the local case. When Compose deploys to a non-local platform it rejects Compose files which use relative host paths with an error. To avoid ambiguities with named volumes, relative paths should always begin with . or ...

Note

For bind mounts, the short syntax creates a directory at the source path on the host if it doesn't exist. This is for backward compatibility with docker-compose legacy. It can be prevented by using long syntax and setting create_host_path to false.

Long syntax

The long form syntax lets you configure additional fields that can't be expressed in the short form.

  • type: The mount type. Either volume, bind, tmpfs, image, npipe, or cluster
  • source: The source of the mount, a path on the host for a bind mount, a Docker image reference for an image mount, or the name of a volume defined in the top-level volumes key. Not applicable for a tmpfs mount.
  • target: The path in the container where the volume is mounted.
  • read_only: Flag to set the volume as read-only.
  • bind: Used to configure additional bind options:
    • propagation: The propagation mode used for the bind.
    • create_host_path: Creates a directory at the source path on host if there is nothing present. Defaults to true.
    • selinux: The SELinux re-labeling option z (shared) or Z (private)
  • volume: Configures additional volume options:
    • nocopy: Flag to disable copying of data from a container when a volume is created.
    • subpath: Path inside a volume to mount instead of the volume root.
  • tmpfs: Configures additional tmpfs options:
    • size: The size for the tmpfs mount in bytes (either numeric or as bytes unit).
    • mode: The file mode for the tmpfs mount as Unix permission bits as an octal number. Introduced in Docker Compose version 2.14.0.
  • image: Configures additional image options:
  • consistency: The consistency requirements of the mount. Available values are platform specific.
Tip

Working with large repositories or monorepos, or with virtual file systems that are no longer scaling with your codebase? Compose now takes advantage of Synchronized file shares and automatically creates file shares for bind mounts. Ensure you're signed in to Docker with a paid subscription and have enabled both Access experimental features and Manage Synchronized file shares with Compose in Docker Desktop's settings.

volumes_from

volumes_from mounts all of the volumes from another service or container. You can optionally specify read-only access ro or read-write rw. If no access level is specified, then read-write access is used.

You can also mount volumes from a container that is not managed by Compose by using the container: prefix.

volumes_from:
  - service_name
  - service_name:ro
  - container:container_name
  - container:container_name:rw

working_dir

working_dir overrides the container's working directory which is specified by the image, for example Dockerfile's WORKDIR.