Note
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
The below requirements are needed on the host that executes this module.
| Parameter | Choices/Defaults | Comments |
|---|---|---|
| allow_unauthenticated boolean added in 2.1 of ansible.builtin |
| 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 added in 2.4 of ansible.builtin |
| If yes, cleans the local repository of retrieved package files that can no longer be downloaded. |
| autoremove boolean added in 2.1 of ansible.builtin |
| 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 added in 1.6 of ansible.builtin | 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 |
| 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 added in 2.4 of ansible.builtin |
| Force usage of apt-get instead of aptitude |
| install_recommends boolean |
| 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 added in 2.1 of ansible.builtin |
| Only upgrade a package if it is already installed. |
| policy_rc_d integer added in 2.8 of ansible.builtin | 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 |
| Will force purging of configuration files if the module state is set to absent. |
| 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. |
| 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. |
| update_cache_retries integer added in 2.10 of ansible.builtin | Default: 5 | Amount of retries if the cache update fails. Also see update_cache_retry_max_delay. |
| update_cache_retry_max_delay integer added in 2.10 of ansible.builtin | Default: 12 | Use an exponential backoff delay for each retry (see update_cache_retries) up to this max delay in seconds. |
| upgrade string added in 1.1 of ansible.builtin |
| 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. |
Note
full, safe and its alias yes) required aptitude up to 2.3, since 2.4 apt-get is used as a fall-back.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)loop: each package will be processed individually, it is much more efficient to pass the list directly to the name option.- 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: https://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
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 ... |
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/ansible/builtin/apt_module.html