# containers.podman.podman_quadlet module – Install or remove Podman Quadlets

Note

This module is part of the containers.podman collection (version 1.20.0).

It is not included in `ansible-core`. To check whether it is installed, run `ansible-galaxy collection list`.

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

To use it in a playbook, specify: `containers.podman.podman_quadlet`.

## Synopsis

- Install or remove Podman Quadlets using `podman quadlet install` and `podman quadlet rm`.

- Creation of quadlet files is handled by resource modules with state=quadlet.

- Updates are handled by removing the existing quadlet and installing the new one.

- Idempotency for local sources uses Podman’s .app/.asset manifest files and direct content comparison.

- For remote URLs, the module always reinstalls to ensure the host matches the configured source (reports changed=true).

- Supports `.quadlets` files containing multiple quadlet sections separated by `---` delimiter (requires Podman 6.0+).

- Each section in a `.quadlets` file must include a `# FileName=<name>` comment to specify the output filename.

## Requirements

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

- podman

## Parameters

Parameter | Comments
--- | ---

all

boolean

Remove all installed quadlets when state=absent (maps to `podman quadlet rm --all`).

Choices:

- `false` ← (default)

- `true`

cmd_args list / elements=string | Extra global arguments to pass to the `podman` command (e.g., `--log-level=debug`). These are placed after the executable and before the subcommand.

debug

boolean

Return additional information which can be helpful for investigations.

Choices:

- `false` ← (default)

- `true`

executable string | Path to `podman` executable if it is not in the `$PATH` on the machine running `podman` Default: `"podman"`
files list / elements=string | Additional non-quadlet files or URLs to install along with the primary src (quadlet application use-case). Passed positionally to `podman quadlet install` after src. For local files, full idempotency is provided. If any file is a URL, the entire install always reports `changed=true` since remote content cannot be verified.

force

boolean

Force removal when state=absent (maps to `podman quadlet rm --force`).

Choices:

- `false`

- `true` ← (default)

name list / elements=string | Name (filename without path) of an installed quadlet to remove when state=absent. If the name does not include the type suffix (e.g. `.container`), the module will attempt to find a matching quadlet file.
quadlet_dir path | Override the target quadlet directory used for idempotency checks. By default it follows Podman defaults. `/etc/containers/systemd/` for root, `~/.config/containers/systemd/` for non-root. Note this is used for content comparison only and is not passed to Podman.

reload_systemd

boolean

Control systemd reload behavior in Podman. When true, pass `--reload-systemd`.

When false, pass `--reload-systemd=false`.

Choices:

- `false`

- `true` ← (default)

src

string

Path to a quadlet file, a directory containing a quadlet application, or a URL to install when state=present.

For local files and directories, full idempotency is provided (content comparison).

For remote URLs, the module always installs fresh and reports `changed=true` since content cannot be verified.

Directory installs support only top-level files; nested subdirectories will cause an error.

state

string

Desired state of quadlet(s).

Choices:

- `"present"` ← (default)

- `"absent"`

## Examples

    - name: Install a simple quadlet file
      containers.podman.podman_quadlet:
        state: present
        src: /tmp/myapp.container

    - name: Install a quadlet application with additional config files
      containers.podman.podman_quadlet:
        state: present
        src: /tmp/myapp.container
        files:
          - /tmp/myapp.conf
          - /tmp/secrets.env

    - name: Install quadlet application from a directory
      containers.podman.podman_quadlet:
        state: present
        src: /tmp/myapp_dir/

    - name: Install with custom quadlet directory (e.g. for system-wide install)
      containers.podman.podman_quadlet:
        state: present
        src: /tmp/myapp.container
        quadlet_dir: /etc/containers/systemd
      become: true

    - name: Remove a specific quadlet
      containers.podman.podman_quadlet:
        state: absent
        name:
          - myapp.container

    - name: Remove multiple quadlets
      containers.podman.podman_quadlet:
        state: absent
        name:
          - myapp.container
          - database.container
          - cache.container

    - name: Remove quadlet without suffix (module resolves to .container, .pod, etc.)
      containers.podman.podman_quadlet:
        state: absent
        name:
          - myapp

    - name: Remove all quadlets (use with caution)
      containers.podman.podman_quadlet:
        state: absent
        all: true

    - name: Install quadlet from a URL (always reports changed=true)
      containers.podman.podman_quadlet:
        state: present
        src: https://example.com/myapp.container

    - name: Install multi-quadlet application from .quadlets file (Podman 6.0+)
      containers.podman.podman_quadlet:
        state: present
        src: /tmp/webapp.quadlets

## Return Values

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

Key | Description
--- | ---
_debug_installed_files list / elements=string | List of currently installed files detected from Podman manifests Returned: when debug=true and state=present and mode is not remote
_debug_spec dictionary | Internal specification used for idempotency detection Returned: when debug=true and state=present
desired_files list / elements=string | List of filenames that should be installed Returned: success
marker_name string | The .app or .asset marker filename used by Podman Returned: success
mode string | Install mode (dir_app, quadlets_app, single_file, or remote) Returned: success
removal_target string | What will be passed to ‘podman quadlet rm’ for updates Returned: success
actions list / elements=string | Human-readable actions performed Returned: always
changed boolean | Whether any change was made Returned: always
podman_actions list / elements=string | Executed podman command lines Returned: always
quadlets list / elements=string | List of affected quadlets with name, path, and scope Returned: always
stderr string | podman stderr Returned: when debug=true
stdout string | podman stdout Returned: when debug=true

### Authors

- Sagi Shnaidman (@sshnaidm)

### Collection links

- Issue Tracker
- Repository (Sources)