AnsibleByExample

ansible.builtin.apt: Install Packages on Debian/Ubuntu

Beginneransibleaptmoduledebian
2024-01-015By Luca Berton

Lesson 1 of 15 in Foundations

Ansible Foundations to Production — full curriculum
  1. 1. Introduction to Ansible and Automation
  2. 2. Installing and Configuring Ansible
  3. 3. Running Ad-Hoc Commands
  4. 4. Writing Your First Playbook
  5. 5. Understanding and Using Modules
  6. 6. Variables and Facts
  7. 7. Conditionals and Loops
  8. 8. Handlers and Idempotency
  9. 9. Structuring Projects with Roles
  10. 10. Inventory Management
  11. 11. Using Ansible Vault for Secrets
  12. 12. Debugging and Troubleshooting
  13. 13. Real-World Automation Examples
  14. 14. Final Project: Deploy a Web Server
  15. 15. Bonus - What's Next with Ansible?
View path overview →

The ansible.builtin.apt module manages packages on Debian-based systems — Debian, Ubuntu, Linux Mint, Kali Linux, and other APT-based distributions. It handles installation, removal, upgrades, cache updates, and .deb file installation.

Module Overview

  • Full name: ansible.builtin.apt
  • Collection: Built-in (shipped with Ansible)
  • Platforms: Debian, Ubuntu, Linux Mint, Kali Linux, Pop!_OS, and other APT-based systems
  • Equivalent for RHEL: ansible.builtin.yum / ansible.builtin.dnf

Key Parameters

ParameterTypeDefaultDescription
namestring/list—Package name(s) to manage
statestringpresentpresent, absent, latest, fixed, build-dep
update_cacheboolfalseRun apt-get update before install
cache_valid_timeint0Seconds to consider cache valid (skip update if recent)
upgradestringnoyes, safe, full, dist
debstring—Path or URL to a .deb file
autoremoveboolfalseRemove unused dependencies
purgeboolfalseRemove package and config files
force_apt_getboolfalseForce use of apt-get instead of aptitude
install_recommendsbooltrueInstall recommended packages
default_releasestring—Target release (e.g., bullseye-backports)
dpkg_optionsstringforce-confdef,force-confoldOptions passed to dpkg

Common Operations

Install a Single Package

- name: Install curl
  ansible.builtin.apt:
    name: curl
    state: present

Install Multiple Packages

- name: Install web server packages
  ansible.builtin.apt:
    name:
      - nginx
      - certbot
      - python3-certbot-nginx
    state: present
    update_cache: true

Install a Specific Version

- name: Install specific PostgreSQL version
  ansible.builtin.apt:
    name: postgresql-16=16.2-1.pgdg22.04+1
    state: present

Install the Latest Version

- name: Ensure nginx is latest version
  ansible.builtin.apt:
    name: nginx
    state: latest
    update_cache: true

Remove a Package

- name: Remove apache2
  ansible.builtin.apt:
    name: apache2
    state: absent

Remove with Config Files (Purge)

- name: Purge apache2 and its configuration
  ansible.builtin.apt:
    name: apache2
    state: absent
    purge: true
    autoremove: true

Install a .deb File

- name: Install Google Chrome from .deb
  ansible.builtin.apt:
    deb: https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb

Or from a local file:

- name: Install local .deb package
  ansible.builtin.apt:
    deb: /tmp/package.deb

Cache Management

Update Cache Before Installing

- name: Install with fresh cache
  ansible.builtin.apt:
    name: nginx
    state: present
    update_cache: true

Smart Cache Update (Skip If Recent)

- name: Update cache only if older than 1 hour
  ansible.builtin.apt:
    name: nginx
    state: present
    update_cache: true
    cache_valid_time: 3600

Update Cache Only (No Install)

- name: Update apt cache
  ansible.builtin.apt:
    update_cache: true

System Upgrades

Upgrade All Packages

- name: Upgrade all packages
  ansible.builtin.apt:
    upgrade: yes
    update_cache: true

Distribution Upgrade

- name: Full distribution upgrade
  ansible.builtin.apt:
    upgrade: dist
    update_cache: true

Safe Upgrade (No Removals)

- name: Safe upgrade (no package removals)
  ansible.builtin.apt:
    upgrade: safe
    update_cache: true

Adding Repositories

Before installing packages from third-party repos:

- name: Add Docker GPG key
  ansible.builtin.apt_key:
    url: https://download.docker.com/linux/ubuntu/gpg
    state: present

- name: Add Docker repository
  ansible.builtin.apt_repository:
    repo: "deb https://download.docker.com/linux/ubuntu {{ ansible_distribution_release }} stable"
    state: present

- name: Install Docker
  ansible.builtin.apt:
    name: docker-ce
    state: present
    update_cache: true

Autoremove Unused Dependencies

- name: Remove unused packages
  ansible.builtin.apt:
    autoremove: true

Practical Playbook: Complete Web Server Setup

---
- name: Set up web server on Ubuntu
  hosts: webservers
  become: true
  tasks:
    - name: Update apt cache
      ansible.builtin.apt:
        update_cache: true
        cache_valid_time: 3600

    - name: Install required packages
      ansible.builtin.apt:
        name:
          - nginx
          - certbot
          - python3-certbot-nginx
          - ufw
          - fail2ban
        state: present

    - name: Remove unnecessary packages
      ansible.builtin.apt:
        name:
          - apache2
          - sendmail
        state: absent
        purge: true

    - name: Clean up unused dependencies
      ansible.builtin.apt:
        autoremove: true

    - name: Ensure nginx is running
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

Common Errors

"Could not get lock /var/lib/dpkg/lock-frontend"

Another apt process is running. Wait or:

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

"E: Unable to locate package"

Package name is wrong or cache is stale:

- name: Update cache and install
  ansible.builtin.apt:
    name: my-package
    state: present
    update_cache: true

"Depends: X but it is not going to be installed"

Dependency conflict. Try:

- name: Force install with dependency resolution
  ansible.builtin.apt:
    name: my-package
    state: present
    install_recommends: false

Conclusion

The ansible.builtin.apt module is the foundation of package management on Debian-based systems. For most use cases, combine state: present with update_cache: true and cache_valid_time: 3600 to ensure fresh package lists without unnecessary network calls. Always use the FQCN ansible.builtin.apt in your playbooks for clarity and future compatibility.

All Tutorials