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

Note

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

You might already have this collection installed if you are using the ansible package. 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
Requirements
Parameters
Examples
Return Values

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

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/containers/podman/podman_quadlet_module.html