# community.docker.docker_compose_v2 module – Manage multi-container Docker applications with Docker Compose v2. — Community.Docker Collection documentation

# community.docker.docker_compose_v2 module – Manage multi-container Docker applications with Docker Compose v2.

Note

This module is part of the community.docker collection (version 3.5.0).

To install it, use: `ansible-galaxy collection install community.docker`. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: `community.docker.docker_compose_v2`.

New in community.docker 3.5.0

- Synopsis

- Requirements

- Parameters

- Attributes

- Examples

- Return Values

## Synopsis

- Uses Docker Compose v2 to manage docker services. This module requires docker-compose >= 2.0.0. and python >= 3.7

- Configuration can be read from a `docker-compose.yaml` file.

- See the examples for more details.

- Supports check mode.

## Requirements

The below requirements are needed on the host that executes this module.

- Python on Whales >= 0.55.0

- docker-compose >= 2.0.0

- python >= 3.7

## Parameters

Parameter | Comments
--- | ---

build

boolean

Use with state `present` to always build images prior to starting the application.

Same as running `docker-compose build` with the pull option.

Images will only be rebuilt if Docker detects a change in the Dockerfile or build directory contents.

Use the nocache option to ignore the image cache when performing the build.

If an existing image is replaced, services using the image will be recreated unless recreate is `never`.

Choices:

- `false` ← (default)

- `true`

nocache

boolean

Use with the build option to ignore the cache during the image build process.

Choices:

- `false` ← (default)

- `true`

project_src path | Path to a directory containing a `docker-compose.yaml` file. Required.

pull

boolean

Use with state `present` to always pull images prior to starting the application.

Same as running `docker-compose pull`.

When a new image is pulled, services using the image will be recreated unless recreate is `never`.

Choices:

- `false` ← (default)

- `true`

recreate

string

By default containers will be recreated when their configuration differs from the service definition.

Setting to `never` ignores configuration differences and leaves existing containers unchanged.

Setting to `always` forces recreation of all existing containers.

Choices:

- `"always"`

- `"never"`

- `"smart"` ← (default)

remove_images

string

Use with state `absent` to remove all images or only local images.

Choices:

- `"all"`

- `"local"`

remove_orphans

boolean

Remove containers for services not defined in the Compose file when not `restarted` or `stopped`.

Choices:

- `false` ← (default)

- `true`

remove_volumes

boolean

Use with state `absent` to remove data volumes.

Choices:

- `false` ← (default)

- `true`

restarted

boolean

Use with state `present` to restart all containers defined in the Compose file.

Choices:

- `false` ← (default)

- `true`

state

string

Desired state of the project.

Specifying `present` is the same as running `docker-compose up` resp. `docker-compose stop` (with stopped) resp. `docker-compose restart` (with restarted).

Specifying `absent` is the same as running `docker-compose down`.

Choices:

- `"absent"`

- `"present"` ← (default)

stopped

boolean

Use with state `present` to stop all containers defined in the Compose file.

Choices:

- `false` ← (default)

- `true`

## Attributes

Attribute | Support | Description
--- | --- | ---
check_mode | Support: full | Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode | Support: none | Will return details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

## Examples

    # Set up a virtual environment for the module and install python on whales
    - name: Set up virtual env for compose v2
      ansible.builtin.pip:
        name:
        - python-on-whales
        virtualenv: ~/ansible-compose-v2

    # Ensure project directory is present
    - name: Create directory if it does not exist
      ansible.builtin.file:
        path: uptime-kuma
        state: directory
    # Create the docker compose file
    - name: Create compose file with content
      ansible.builtin.copy:
        dest: "uptime-kuma/docker-compose.yaml"
        content: |
          version: '3.3'

          services:
            uptime-kuma:
              image: louislam/uptime-kuma:1
              container_name: uptime-kuma
              volumes:
                - ./uptime-kuma-data:/app/data
              ports:
                - 3001:3001
              restart: always

    # Tear down any containers, remove images and volumes
    - name: Tear down all existing containers
      vars:
        ansible_python_interpreter: ansible-compose-v2/bin/python
      community.docker.docker_compose_v2:
        project_src: uptime-kuma/docker-compose.yaml
        remove_volumes: true
        remove_orphans: true
        remove_images: all
        state: absent

    # Pull the latest image and then start services
    - name: Pull image and start service
      vars:
        ansible_python_interpreter: ansible-compose-v2/bin/python
      community.docker.docker_compose_v2:
        project_src: uptime-kuma/docker-compose.yaml
        pull: true
        state: present

    # Restart services
    - name: Restart service
      vars:
        ansible_python_interpreter: ansible-compose-v2/bin/python
      community.docker.docker_compose_v2:
        project_src: uptime-kuma/docker-compose.yaml
        restarted: true
        state: present

    # Stop services
    - name: Stop service
      vars:
        ansible_python_interpreter: ansible-compose-v2/bin/python
      community.docker.docker_compose_v2:
        project_src: uptime-kuma/docker-compose.yaml
        stopped: true
        state: present

    # Start services, recreating all containers
    - name: Recreate service
      vars:
        ansible_python_interpreter: ansible-compose-v2/bin/python
      community.docker.docker_compose_v2:
        project_src: uptime-kuma/docker-compose.yaml
        recreate: always
        state: present

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Description
--- | ---
actions list / elements=string | List stating which compose commands were run (not the entire command itself). Returned: success Sample: `["pull", "up"]`
changed boolean | If something was changed (currently, changed is (almost) always true as there is no check of current state). Returned: always Sample: `true`
msg boolean | In docker failures, has docker command + some description. In other failures, stringified exception is returned. In success, descriptive message of what happened. Returned: always Sample: `true`
rc string | Return code of executed docker command. Returned: failure from docker Sample: `"12"`

### Authors

- Sid Sun (@SidSun)

### Collection links

Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication