Documentation

apt - Manages apt-packages

Synopsis

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

Requirements (on host that executes module)

  • python-apt
  • aptitude

Options

parameter required default choices comments
allow_unauthenticated
(added in 2.1)
 no no
  • yes
  • no
Ignore if packages cannot be authenticated. This is useful for bootstrapping environments that manage their own apt-key setup.
autoremove
(added in 2.1)
 no
  • yes
  • no
If yes, remove unused dependency packages for all module states except build-dep.

aliases: autoclean
cache_valid_time
 no
    If update_cache is specified and the last run is less or equal than cache_valid_time seconds ago, the update_cache gets skipped.
    deb
    (added in 1.6)
    		 no
      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)
      default_release
      		 no
        Corresponds to the -t option for apt and sets pin priorities
        dpkg_options
        		 no 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
          		 no no
          • yes
          • no
          If yes, force installs/removes.
          install_recommends
          		 no
          • yes
          • no
          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.
          name
          		 no
            A package name, 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. Note that 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)

            aliases: pkg, package
            only_upgrade
            (added in 2.1)
            		 no
              Only install/upgrade a package it it is already installed.
              purge
              		 no
              • yes
              • no
              Will force purging of configuration files if the module state is set to absent.
              state
              		 no present
              • latest
              • absent
              • present
              • build-dep
              Indicates the desired package state. latest ensures that the latest version is installed. build-dep ensures the package build dependencies are installed.
              update_cache
              		 no
              • yes
              • no
              Run the equivalent of apt-get update before the operation. Can be run as part of the package installation or as a separate step.
              upgrade
              		 no no
              • no
              • yes
              • safe
              • full
              • dist
              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.

              Examples

              # Update repositories cache and install "foo" package
- apt: name=foo update_cache=yes

# Remove "foo" package
- apt: name=foo state=absent

# Install the package "foo"
- apt: name=foo state=present

# Install the version '1.00' of package "foo"
- apt: name=foo=1.00 state=present

# 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

# Install latest version of "openjdk-6-jdk" ignoring "install-recommends"
- apt: name=openjdk-6-jdk state=latest install_recommends=no

# Update all packages to the latest version
- apt: upgrade=dist

# Run the equivalent of "apt-get update" as a separate step
- apt: update_cache=yes

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

# Pass options to dpkg on run
- apt: upgrade=dist update_cache=yes dpkg_options='force-confold,force-confdef'

# Install a .deb package
- apt: deb=/tmp/mypackage.deb

# Install the build dependencies for package "foo"
- apt: pkg=foo state=build-dep

# Install a .deb package from the internet.
- apt: deb=https://example.com/python-ppq_0.1-1_all.deb

              Return Values

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

              name description returned type sample
              cache_updated if the cache was updated or not success, in some cases boolean True
              stdout output from apt success, when needed string Reading package lists... Building dependency tree... Reading state information... The following extra packages will be installed: apache2-bin ...
              stderr error output from apt success, when needed string AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.1.1. Set the 'ServerName' directive globally to ...
              cache_update_time time of the last cache update (0 if unknown) success, in some cases datetime 1425828348000


              Notes

              Note

              Three of the upgrade modes (full, safe and its alias yes) require aptitude, otherwise apt-get suffices.

              This is a Core Module

              For more information on what this means please read Core Modules

              For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.