Ansible apt Module: Install Packages on Ubuntu/Debian (Examples)

How to Install a package with Ansible in Debian-like systems?

I’m going to show you a live Playbook with some simple Ansible code. I’m Luca Berton and welcome to today’s episode of Ansible Pilot

See also: Install Docker in Debian-like systems - Ansible module apt_key, apt_repository and apt

Ansible Install a package in Debian-like systems

Today we’re talking about the Ansible module APT. The full name is “ansible.builtin.apt” which means is part of the collection of modules “builtin” with ansible and shipped with it. This module is pretty stable and out for years. It works on Debian-like operating systems and Manages packages with the apt package manager. It’s similar to the yum or DNF module for RedHat-like operating systems.

Main Parameters

• name _string_ • state _string_ • update_cache _boolean_

The parameter list is pretty wide but this three are the most important options. In the “name” parameter you are going to specify the name of the package or the specific version you would like to install. The state specifies the action that we would like to perform. In our case for install is “present”. “update_cache” forces to update the repository metadata before the installation. It could be useful to make sure that the repository is up-to-date.

See also: Install Google Chrome in Debian like systems - Ansible module apt_key, apt_repository and apt

Demo

Let’s jump in a real-life playbook to install a package in Debian-like systems with Ansible

---
- name: module apt Playbook
  hosts: all
  become: true
  tasks:
    - name: install package
      apt:
        name: curl
        state: present

code with ❤️ in GitHub

Conclusion

Now you know how to install a package and a specific version of a package in Debian-like systems.

See also: Install PostgreSQL in Debian-like systems - Ansible modules apt, stat, shell, service

Advanced apt Module Usage

Install multiple packages

- name: Install multiple packages
  ansible.builtin.apt:
    name:
      - curl
      - wget
      - git
      - htop
      - vim
    state: present
    update_cache: true
  become: true

Install a specific version

- name: Install specific nginx version
  ansible.builtin.apt:
    name: nginx=1.24.0-1~jammy
    state: present
  become: true

Update all packages (equivalent to apt upgrade)

- name: Update all packages
  ansible.builtin.apt:
    upgrade: dist
    update_cache: true
    cache_valid_time: 3600  # Only update cache if older than 1 hour
  become: true

Remove a package

- name: Remove package
  ansible.builtin.apt:
    name: apache2
    state: absent
  become: true
- name: Remove package and its config files (purge)
  ansible.builtin.apt:
    name: apache2
    state: absent
    purge: true
  become: true

Install from a .deb file

- name: Download and install .deb package
  ansible.builtin.apt:
    deb: https://example.com/package.deb
  become: true

Add an APT repository and install

- name: Add Docker GPG key
  ansible.builtin.apt_key:
    url: https://download.docker.com/linux/ubuntu/gpg
    state: present
  become: true
- name: Add Docker repository
  ansible.builtin.apt_repository:
    repo: "deb https://download.docker.com/linux/ubuntu {{ ansible_distribution_release }} stable"
    state: present
  become: true
- name: Install Docker
  ansible.builtin.apt:
    name: docker-ce
    state: present
    update_cache: true
  become: true

Key Parameters Reference

| Parameter | Type | Description | |-----------|------|-------------| | name | string/list | Package name(s) | | state | string | present, absent, latest, fixed | | update_cache | bool | Run apt update before install | | cache_valid_time | int | Seconds before cache is considered stale | | upgrade | string | dist, full, safe, yes | | purge | bool | Remove config files with absent | | deb | string | Path or URL to .deb file | | force_apt_get | bool | Use apt-get instead of aptitude | | autoremove | bool | Remove unused dependencies |

FAQ

What's the difference between apt and package module?

ansible.builtin.apt is Debian/Ubuntu-specific with full apt features. ansible.builtin.package is generic and works across distros but has fewer options. Use apt when you know the target is Debian-based.

How do I handle "dpkg lock" errors?

- name: Wait for apt lock
  ansible.builtin.shell: while fuser /var/lib/dpkg/lock-frontend >/dev/null 2>&1; do sleep 5; done
  become: true
  changed_when: false

How do I pin a package version to prevent upgrades?

- name: Hold package version
  ansible.builtin.dpkg_selections:
    name: nginx
    selection: hold
  become: true

Related Articles

• the Ansible become reference • Ansible role best practices