ansible.builtin.apt module – Manages apt-packages

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name apt even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.apt for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis

  • Manages apt packages (such as for Debian/Ubuntu).

Requirements

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

  • python-apt (python 2)
  • python3-apt (python 3)
  • aptitude (before 2.4)

Parameters

Parameter

Comments

allow_change_held_packages

boolean

added in ansible-core 2.13

Allows changing the version of a package which is on the apt hold list.

Choices:

  • false ← (default)
  • true

allow_downgrade

aliases: allow-downgrade, allow_downgrades, allow-downgrades

boolean

added in ansible-core 2.12

Corresponds to the --allow-downgrades option for apt.

This option enables the named package and version to replace an already installed higher version of that package.

Note that setting allow_downgrade=true can make this module behave in a non-idempotent way.

(The task could end up with a set of packages that does not match the complete list of specified packages to install).

allow_downgrade is only supported by apt and will be ignored if aptitude is detected or specified.

Choices:

  • false ← (default)
  • true

allow_unauthenticated

aliases: allow-unauthenticated

boolean

Ignore if packages cannot be authenticated. This is useful for bootstrapping environments that manage their own apt-key setup.

allow_unauthenticated is only supported with state: install/present.

Choices:

  • false ← (default)
  • true

autoclean

boolean

If true, cleans the local repository of retrieved package files that can no longer be downloaded.

Choices:

  • false ← (default)
  • true

autoremove

boolean

If true, remove unused dependency packages for all module states except build-dep. It can also be used as the only option.

Previous to version 2.4, autoclean was also an alias for autoremove, now it is its own separate command. See documentation for further information.

Choices:

  • false ← (default)
  • true

cache_valid_time

integer

Update the apt cache if it is older than the cache_valid_time. This option is set in seconds.

As of Ansible 2.4, if explicitly set, this sets update_cache=yes.

Default: 0

clean

boolean

added in ansible-core 2.13

Run the equivalent of apt-get clean to clear out the local repository of retrieved package files. It removes everything but the lock file from /var/cache/apt/archives/ and /var/cache/apt/archives/partial/.

Can be run as part of the package installation (clean runs before install) or as a separate step.

Choices:

  • false ← (default)
  • true

deb

path

Path to a .deb package on the remote machine.

If :// in the path, ansible will attempt to download deb before installing. (Version added 2.1)

Requires the xz-utils package to extract the control file of the deb package to install.

default_release

aliases: default-release

string

Corresponds to the -t option for apt and sets pin priorities.

dpkg_options

string

Add dpkg options to apt command. Defaults to -o "Dpkg::Options::=--force-confdef" -o "Dpkg::Options::=--force-confold".

Options should be supplied as comma separated list.

Default: "force-confdef,force-confold"

fail_on_autoremove

boolean

added in ansible-core 2.11

Corresponds to the --no-remove option for apt.

If true, it is ensured that no packages will be removed or the task will fail.

fail_on_autoremove is only supported with state except absent.

fail_on_autoremove is only supported by apt and will be ignored if aptitude is detected or specified.

Choices:

  • false ← (default)
  • true

force

boolean

Corresponds to the --force-yes to apt-get and implies allow_unauthenticated=yes and allow_downgrade=yes.

This option will disable checking both the packages’ signatures and the certificates of the web servers they are downloaded from.

This option *is not* the equivalent of passing the -f flag to apt-get on the command line.

**This is a destructive operation with the potential to destroy your system, and it should almost never be used.** Please also see man apt-get for more information.

Choices:

  • false ← (default)
  • true

force_apt_get

boolean

Force usage of apt-get instead of aptitude.

Choices:

  • false ← (default)
  • true

install_recommends

aliases: install-recommends

boolean

Corresponds to the --no-install-recommends option for apt. true installs recommended packages. false does not install recommended packages. By default, Ansible will use the same defaults as the operating system. Suggested packages are never installed.

Choices:

  • false
  • true

lock_timeout

integer

added in ansible-core 2.12

How many seconds will this action wait to acquire a lock on the apt db.

Sometimes there is a transitory lock and this will retry at least until timeout is hit.

Default: 60

name

aliases: package, pkg

list / elements=string

A list of package names, like foo, or package specifier with version, like foo=1.0 or foo>=1.0. Name wildcards (fnmatch) like apt* and version wildcards like foo=1.0* are also supported.

Do not use single or double quotes around the version when referring to the package name with a specific version, such as foo=1.0 or foo>=1.0.

only_upgrade

boolean

Only upgrade a package if it is already installed.

Choices:

  • false ← (default)
  • true

policy_rc_d

integer

added in Ansible 2.8

Force the exit code of /usr/sbin/policy-rc.d.

For example, if policy_rc_d=101 the installed package will not trigger a service start.

If /usr/sbin/policy-rc.d already exists, it is backed up and restored after the package installation.

If null, the /usr/sbin/policy-rc.d is not created/changed.

purge

boolean

Will force purging of configuration files if state=absent or autoremove=yes.

Choices:

  • false ← (default)
  • true

state

string

Indicates the desired package state. latest ensures that the latest version is installed. build-dep ensures the package build dependencies are installed. fixed attempt to correct a system with broken dependencies in place.

Choices:

  • "absent"
  • "build-dep"
  • "latest"
  • "present" ← (default)
  • "fixed"

update_cache

aliases: update-cache

boolean

Run the equivalent of apt-get update before the operation. Can be run as part of the package installation or as a separate step.

Default is not to update the cache.

Choices:

  • false
  • true

update_cache_retries

integer

added in ansible-base 2.10

Amount of retries if the cache update fails. Also see update_cache_retry_max_delay.

Default: 5

update_cache_retry_max_delay

integer

added in ansible-base 2.10

Use an exponential backoff delay for each retry (see update_cache_retries) up to this max delay in seconds.

Default: 12

upgrade

string

If yes or safe, performs an aptitude safe-upgrade.

If full, performs an aptitude full-upgrade.

If dist, performs an apt-get dist-upgrade.

Note: This does not upgrade a specific package, use state=latest for that.

Note: Since 2.4, apt-get is used as a fall-back if aptitude is not present.

Choices:

  • "dist"
  • "full"
  • "no" ← (default)
  • "safe"
  • "yes"

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

diff_mode

Support: full

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platform: debian

Target OS/families that can be operated against

Notes

Note

  • Three of the upgrade modes (full, safe and its alias true) required aptitude up to 2.3, since 2.4 apt-get is used as a fall-back.
  • In most cases, packages installed with apt will start newly installed services by default. Most distributions have mechanisms to avoid this. For example when installing Postgresql-9.5 in Debian 9, creating an executable shell script (/usr/sbin/policy-rc.d) that throws a return code of 101 will stop Postgresql 9.5 starting up after install. Remove the file or its execute permission afterward.
  • The apt-get commandline supports implicit regex matches here but we do not because it can let typos through easier (If you typo foo as fo apt-get would install packages that have “fo” in their name with a warning and a prompt for the user. Since there are no warnings and prompts before installing, we disallow this. Use an explicit fnmatch pattern if you want wildcarding).
  • 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.
  • When default_release is used, an implicit priority of 990 is used. This is the same behavior as apt-get -t.
  • When an exact version is specified, an implicit priority of 1001 is used.
  • If the interpreter can’t import python-apt/python3-apt the module will check for it in system-owned interpreters as well. If the dependency can’t be found, the module will attempt to install it. If the dependency is found or installed, the module will be respawned under the correct interpreter.

Examples

- name: Install apache httpd (state=present is optional)
  ansible.builtin.apt:
    name: apache2
    state: present

- name: Update repositories cache and install "foo" package
  ansible.builtin.apt:
    name: foo
    update_cache: yes

- name: Remove "foo" package
  ansible.builtin.apt:
    name: foo
    state: absent

- name: Install the package "foo"
  ansible.builtin.apt:
    name: foo

- name: Install a list of packages
  ansible.builtin.apt:
    pkg:
    - foo
    - foo-tools

- name: Install the version '1.00' of package "foo"
  ansible.builtin.apt:
    name: foo=1.00

- name: Update the repository cache and update package "nginx" to latest version using default release squeeze-backport
  ansible.builtin.apt:
    name: nginx
    state: latest
    default_release: squeeze-backports
    update_cache: yes

- name: Install the version '1.18.0' of package "nginx" and allow potential downgrades
  ansible.builtin.apt:
    name: nginx=1.18.0
    state: present
    allow_downgrade: yes

- name: Install zfsutils-linux with ensuring conflicted packages (e.g. zfs-fuse) will not be removed.
  ansible.builtin.apt:
    name: zfsutils-linux
    state: latest
    fail_on_autoremove: yes

- name: Install latest version of "openjdk-6-jdk" ignoring "install-recommends"
  ansible.builtin.apt:
    name: openjdk-6-jdk
    state: latest
    install_recommends: no

- name: Update all packages to their latest version
  ansible.builtin.apt:
    name: "*"
    state: latest

- name: Upgrade the OS (apt-get dist-upgrade)
  ansible.builtin.apt:
    upgrade: dist

- name: Run the equivalent of "apt-get update" as a separate step
  ansible.builtin.apt:
    update_cache: yes

- name: Only run "update_cache=yes" if the last one is more than 3600 seconds ago
  ansible.builtin.apt:
    update_cache: yes
    cache_valid_time: 3600

- name: Pass options to dpkg on run
  ansible.builtin.apt:
    upgrade: dist
    update_cache: yes
    dpkg_options: 'force-confold,force-confdef'

- name: Install a .deb package
  ansible.builtin.apt:
    deb: /tmp/mypackage.deb

- name: Install the build dependencies for package "foo"
  ansible.builtin.apt:
    pkg: foo
    state: build-dep

- name: Install a .deb package from the internet
  ansible.builtin.apt:
    deb: https://example.com/python-ppq_0.1-1_all.deb

- name: Remove useless packages from the cache
  ansible.builtin.apt:
    autoclean: yes

- name: Remove dependencies that are no longer required
  ansible.builtin.apt:
    autoremove: yes

- name: Remove dependencies that are no longer required and purge their configuration files
  ansible.builtin.apt:
    autoremove: yes
    purge: true

- name: Run the equivalent of "apt-get clean" as a separate step
  ansible.builtin.apt:
    clean: yes

Return Values

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

Key

Description

cache_update_time

integer

time of the last cache update (0 if unknown)

Returned: success, in some cases

Sample: 1425828348000

cache_updated

boolean

if the cache was updated or not

Returned: success, in some cases

Sample: true

stderr

string

error output from apt

Returned: success, when needed

Sample: "AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.1.1. Set the 'ServerName' directive globally to ..."

stdout

string

output from apt

Returned: success, when needed

Sample: "Reading package lists...\nBuilding dependency tree...\nReading state information...\nThe following extra packages will be installed:\n  apache2-bin ..."

Authors

  • Matthew Williams (@mgwilliams)

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