ansible.builtin.apt - Manages apt-packages

ansible.builtin.apt - Manages apt-packages

This module is part of ansible-base and included in all Ansible installations. In most cases, you can use the short module name apt even without specifying the collections: keyword. Despite that, we recommend you use the FQCN for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

New in version 0.0.2: of ansible.builtin

Synopsis
Requirements
Parameters
Notes
Examples
Return Values

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 Choices/Defaults Comments

allow_unauthenticated
boolean

no ←
yes

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

autoclean
boolean

no ←
yes

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

autoremove
boolean

no ←
yes

If yes, 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.

cache_valid_time
string
Default:

0

Update the apt cache if its 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.

deb
string

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
string

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

dpkg_options
string
Default:

"force-confdef,force-confold"

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

force
boolean

no ←
yes

Corresponds to the --force-yes to apt-get and implies allow_unauthenticated: 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.

force_apt_get
boolean

no ←
yes

Force usage of apt-get instead of aptitude

install_recommends
boolean

no
yes

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

aliases: install-recommends

name
list / elements=string

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

aliases: package, pkg

only_upgrade
boolean

no ←
yes

Only upgrade a package if it is already installed.

policy_rc_d
integer

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 exist, it is backed up and restored after the package installation.
If null, the /usr/sbin/policy-rc.d isn't created/changed.

purge
boolean

no ←
yes

Will force purging of configuration files if the module state is set to absent.

state
string

absent
build-dep
latest
present ←
fixed

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.

update_cache
boolean

no
yes

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.

update_cache_retries
integer
Default:

5

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

update_cache_retry_max_delay
integer
Default:

12

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

upgrade
string

dist
full
no ←
safe
yes

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.

Notes

Three of the upgrade modes (full, safe and its alias yes) 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 excutable 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 remove its execute permission afterwards.
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 we don't have 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.

Examples

- name: Install apache httpd (state=present is optional) apt: name: apache2 state: present - name: Update repositories cache and install "foo" package apt: name: foo update_cache: yes - name: Remove "foo" package apt: name: foo state: absent - name: Install the package "foo" apt: name: foo - name: Install a list of packages apt: pkg: - foo - foo-tools - name: Install the version '1.00' of package "foo" apt: name: foo=1.00 - name: Update the repository cache and update package "nginx" to latest version using default release squeeze-backport apt: name: nginx state: latest default_release: squeeze-backports update_cache: yes - name: Install latest version of "openjdk-6-jdk" ignoring "install-recommends" apt: name: openjdk-6-jdk state: latest install_recommends: no - name: Update all packages to their latest version apt: name: "*" state: latest - name: Upgrade the OS (apt-get dist-upgrade) apt: upgrade: dist - name: Run the equivalent of "apt-get update" as a separate step apt: update_cache: yes - name: Only run "update_cache=yes" if the last one is more than 3600 seconds ago apt: update_cache: yes cache_valid_time: 3600 - name: Pass options to dpkg on run apt: upgrade: dist update_cache: yes dpkg_options: 'force-confold,force-confdef' - name: Install a .deb package apt: deb: /tmp/mypackage.deb - name: Install the build dependencies for package "foo" apt: pkg: foo state: build-dep - name: Install a .deb package from the internet apt: deb: //example.com/python-ppq_0.1-1_all.deb - name: Remove useless packages from the cache apt: autoclean: yes - name: Remove dependencies that are no longer required apt: autoremove: yes # Sometimes apt tasks fail because apt is locked by an autoupdate or by a race condition on a thread. # To check for a lock file before executing, and keep trying until the lock file is released: - name: Install packages only when the apt process is not locked apt: name: foo state: present register: apt_action retries: 100 until: apt_action is success or ('Failed to lock apt for exclusive operation' not in apt_action.msg and '/var/lib/dpkg/lock' not in apt_action.msg)

Return Values

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

Key Returned Description

cache_update_time
integer
success, in some cases
time of the last cache update (0 if unknown)

Sample:
1425828348000

cache_updated
boolean
success, in some cases
if the cache was updated or not

Sample:
True

stderr
string
success, when needed
error output from apt

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
success, when needed
output from apt

Sample:
Reading package lists... Building dependency tree... Reading state information... The following extra packages will be installed: apache2-bin ...

Authors

Matthew Williams (@mgwilliams)

Parameter	Choices/Defaults	Comments
allow_unauthenticated boolean	no ← yes	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
autoclean boolean	no ← yes	If yes, cleans the local repository of retrieved package files that can no longer be downloaded.
autoremove boolean	no ← yes	If yes, 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.
cache_valid_time string	Default: 0	Update the apt cache if its 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.
deb string		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 string		Corresponds to the -t option for apt and sets pin priorities
dpkg_options string	Default: "force-confdef,force-confold"	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
force boolean	no ← yes	Corresponds to the --force-yes to apt-get and implies allow_unauthenticated: 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.
force_apt_get boolean	no ← yes	Force usage of apt-get instead of aptitude
install_recommends boolean	no yes	Corresponds to the --no-install-recommends option for apt. yes installs recommended packages. no does not install recommended packages. By default, Ansible will use the same defaults as the operating system. Suggested packages are never installed. aliases: install-recommends
name list / elements=string		A list of package names, like foo, or package specifier with version, like foo=1.0. Name wildcards (fnmatch) like apt* and version wildcards like foo=1.0* are also supported. aliases: package, pkg
only_upgrade boolean	no ← yes	Only upgrade a package if it is already installed.
policy_rc_d integer		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 exist, it is backed up and restored after the package installation. If null, the /usr/sbin/policy-rc.d isn't created/changed.
purge boolean	no ← yes	Will force purging of configuration files if the module state is set to absent.
state string	absent build-dep latest present ← fixed	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.
update_cache boolean	no yes	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.
update_cache_retries integer	Default: 5	Amount of retries if the cache update fails. Also see update_cache_retry_max_delay.
update_cache_retry_max_delay integer	Default: 12	Use an exponential backoff delay for each retry (see update_cache_retries) up to this max delay in seconds.
upgrade string	dist full no ← safe yes	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.