community.general.pacman module – Manage packages with pacman

Note

This module is part of the community.general collection (version 4.8.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 community.general.

To use it in a playbook, specify: community.general.pacman.

Synopsis

  • Manage packages with the pacman package manager, which is used by Arch Linux and its variants.

Parameters

Parameter

Comments

executable

string

added in 3.1.0 of community.general

Path of the binary to use. This can either be pacman or a pacman compatible AUR helper.

Pacman compatibility is unfortunately ill defined, in particular, this modules makes extensive use of the --print-format directive which is known not to be implemented by some AUR helpers (notably, yay).

Beware that AUR helpers might behave unexpectedly and are therefore not recommended.

Default: “pacman”

extra_args

string

Additional option to pass to pacman when enforcing state.

force

boolean

When removing packages, forcefully remove them, without any checks. Same as extra_args="--nodeps --nodeps". When combined with update_cache, force a refresh of all package databases. Same as update_cache_extra_args="--refresh --refresh".

Choices:

  • no ← (default)

  • yes

name

aliases: package, pkg

list / elements=string

Name or list of names of the package(s) or file(s) to install, upgrade, or remove. Can’t be used in combination with upgrade.

remove_nosave

boolean

added in 4.6.0 of community.general

When removing packages, do not save modified configuration files as .pacsave files. (passes --nosave to pacman)

Choices:

  • no ← (default)

  • yes

state

string

Whether to install (present or installed, latest), or remove (absent or removed) a package.

present and installed will simply ensure that a desired package is installed.

latest will update the specified package if it is not of the latest available version.

absent and removed will remove the specified package.

Choices:

  • absent

  • installed

  • latest

  • present ← (default)

  • removed

update_cache

aliases: update-cache

boolean

Whether or not to refresh the master package lists.

This can be run as part of a package installation or as a separate step.

Alias update-cache has been deprecated and will be removed in community.general 5.0.0.

If not specified, it defaults to false.

Please note that this option will only have an influence on the module’s changed state if name and upgrade are not specified. This will change in community.general 5.0.0. See the examples for how to make the module behave as it will in 5.0.0 right now, or how to keep the current behavior with 5.0.0 and later.

Choices:

  • no

  • yes

update_cache_extra_args

string

Additional option to pass to pacman when enforcing update_cache.

upgrade

boolean

Whether or not to upgrade the whole system. Can’t be used in combination with name.

If not specified, it defaults to false.

Choices:

  • no

  • yes

upgrade_extra_args

string

Additional option to pass to pacman when enforcing upgrade.

Notes

Note

  • When used with a loop: each package will be processed individually, it is much more efficient to pass the list directly to the name option.

  • To use an AUR helper (executable option), a few extra setup steps might be required beforehand. For example, a dedicated build user with permissions to install packages could be necessary.

Examples

- name: Install package foo from repo
  community.general.pacman:
    name: foo
    state: present

- name: Install package bar from file
  community.general.pacman:
    name: ~/bar-1.0-1-any.pkg.tar.xz
    state: present

- name: Install package foo from repo and bar from file
  community.general.pacman:
    name:
      - foo
      - ~/bar-1.0-1-any.pkg.tar.xz
    state: present

- name: Install package from AUR using a Pacman compatible AUR helper
  community.general.pacman:
    name: foo
    state: present
    executable: yay
    extra_args: --builddir /var/cache/yay

- name: Upgrade package foo
  # The 'changed' state of this call will only indicate whether foo was
  # installed/upgraded, but not on whether the cache was updated. This
  # will change in community.general 5.0.0!
  community.general.pacman:
    name: foo
    state: latest
    update_cache: yes

- name: Remove packages foo and bar
  community.general.pacman:
    name:
      - foo
      - bar
    state: absent

- name: Recursively remove package baz
  community.general.pacman:
    name: baz
    state: absent
    extra_args: --recursive

- name: Run the equivalent of "pacman -Sy" as a separate step
  community.general.pacman:
    update_cache: yes

- name: Run the equivalent of "pacman -Su" as a separate step
  community.general.pacman:
    upgrade: yes

- name: Run the equivalent of "pacman -Syu" as a separate step
  # The 'changed' state of this call will only indicate whether
  # something was upgraded, but not on whether the cache was
  # updated. This will change in community.general 5.0.0!
  #
  # To keep the old behavior, add the following to the task:
  #
  #   register: result
  #   changed_when: result.packages | length > 0
  #
  # To already switch to the new behavior now, add:
  #
  #   register: result
  #   changed_when: result is changed or result.cache_updated
  #
  # Note that both constructs only work with community.general 4.6.0+.
  # For compatibility with older versions of community.general, you
  # have to use
  #
  #   changed_when: result.packages | default([]) | length > 0
  #
  # respectively
  #
  #   changed_when: result is changed or (result.cache_updated | default(false))
  community.general.pacman:
    update_cache: yes
    upgrade: yes

- name: Run the equivalent of "pacman -Rdd", force remove package baz
  community.general.pacman:
    name: baz
    state: absent
    force: yes

Return Values

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

Key

Description

cache_updated

boolean

added in 4.6.0 of community.general

The changed status of pacman -Sy.

Useful when name or upgrade=true are specified next to update_cache=true.

Returned: success, when update_cache=true

Sample: false

packages

list / elements=string

A list of packages that have been changed.

Before community.general 4.5.0 this was only returned when upgrade=true. In community.general 4.5.0, it was sometimes omitted when the package list is empty, but since community.general 4.6.0 it is always returned when name is specified or upgrade=true.

Returned: success and name is specified or upgrade=true

Sample: [“package”, “other-package”]

stderr

string

added in 4.1.0 of community.general

Error output from pacman.

Returned: success, when needed

Sample: “warning: libtool: local (2.4.6+44+gb9b44533-14) is newer than core (2.4.6+42+gb88cebd5-15) warning …”

stdout

string

added in 4.1.0 of community.general

Output from pacman.

Returned: success, when needed

Sample: “:: Synchronizing package databases… core is up to date :: Starting full system upgrade…”

Authors

  • Indrajit Raychaudhuri (@indrajitr)

  • Aaron Bull Schaefer (@elasticdog)

  • Maxime de Roucy (@tchernomax)

  • Jean Raby (@jraby)