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 |
|---|---|
Allows changing the version of a package which is on the apt hold list. Choices:
|
|
Corresponds to the This option enables the named package and version to replace an already installed higher version of that package. Note that setting (The task could end up with a set of packages that does not match the complete list of specified packages to install).
Choices:
|
|
Ignore if packages cannot be authenticated. This is useful for bootstrapping environments that manage their own apt-key setup.
Choices:
|
|
If Choices:
|
|
If Previous to version 2.4, Choices:
|
|
Update the apt cache if it is older than the As of Ansible 2.4, if explicitly set, this sets Default: |
|
Run the equivalent of Can be run as part of the package installation (clean runs before install) or as a separate step. Choices:
|
|
Path to a .deb package on the remote machine. If Requires the |
|
Corresponds to the |
|
Add Options should be supplied as comma separated list. Default: |
|
Corresponds to the If
Choices:
|
|
Corresponds to the 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 **This is a destructive operation with the potential to destroy your system, and it should almost never be used.** Please also see Choices:
|
|
Force usage of apt-get instead of aptitude. Choices:
|
|
Corresponds to the Choices:
|
|
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: |
|
A list of package names, like Do not use single or double quotes around the version when referring to the package name with a specific version, such as |
|
Only upgrade a package if it is already installed. Choices:
|
|
Force the exit code of For example, if If If |
|
Will force purging of configuration files if Choices:
|
|
Indicates the desired package state. Choices:
|
|
Run the equivalent of Default is not to update the cache. Choices:
|
|
Amount of retries if the cache update fails. Also see Default: |
|
Use an exponential backoff delay for each retry (see Default: |
|
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:
|
Attributes
Attribute |
Support |
Description |
|---|---|---|
Support: full |
Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped. |
|
Support: full |
Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
|
Platform: debian |
Target OS/families that can be operated against |
Notes
Note
Three of the upgrade modes (
full,safeand its aliastrue) requiredaptitudeup to 2.3, since 2.4apt-getis 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-getcommandline supports implicit regex matches here but we do not because it can let typos through easier (If you typofooasfoapt-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 thenameoption.When
default_releaseis used, an implicit priority of 990 is used. This is the same behavior asapt-get -t.When an exact version is specified, an implicit priority of 1001 is used.
If the interpreter can’t import
python-apt/python3-aptthe 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 |
|---|---|
time of the last cache update (0 if unknown) Returned: success, in some cases Sample: |
|
if the cache was updated or not Returned: success, in some cases Sample: |
|
error output from apt Returned: success, when needed Sample: |
|
output from apt Returned: success, when needed Sample: |