ansible.builtin.apt_repository module – Add and remove APT repositories

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_repository even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.apt_repository for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis

  • Add or remove an APT repositories in Ubuntu and Debian.

Requirements

The below requirements are needed on the host that executes this module.

  • python-apt (python 2)

  • python3-apt (python 3)

  • apt-key or gpg

Parameters

Parameter

Comments

codename

string

Override the distribution codename to use for PPA repositories. Should usually only be set when working with a PPA on a non-Ubuntu target (for example, Debian or Mint).

filename

string

Sets the name of the source list file in sources.list.d. Defaults to a file name based on the repository source url. The .list extension will be automatically added.

install_python_apt

boolean

Whether to automatically try to install the Python apt library or not, if it is not already installed. Without this library, the module does not work.

Runs apt-get install python-apt for Python 2, and apt-get install python3-apt for Python 3.

Only works with the system Python 2 or Python 3. If you are using a Python on the remote that is not the system Python, set install_python_apt=false and ensure that the Python apt library for your Python version is installed some other way.

Choices:

  • false

  • true ← (default)

mode

any

The octal mode for newly created files in sources.list.d.

Default is what system uses (probably 0644).

repo

string / required

A source string for the repository.

state

string

A source string state.

Choices:

  • "absent"

  • "present" ← (default)

update_cache

aliases: update-cache

boolean

Run the equivalent of apt-get update when a change occurs. Cache updates are run after making changes.

Choices:

  • false

  • true ← (default)

update_cache_retries

integer

added in ansible-base 2.10

Amount of retries if the cache update fails. Also see update_cache_retry_max_delay.

Default: 5

update_cache_retry_max_delay

integer

added in ansible-base 2.10

Use an exponential backoff delay for each retry (see update_cache_retries) up to this max delay in seconds.

Default: 12

validate_certs

boolean

If false, SSL certificates for the target repo will not be validated. This should only be used on personally controlled sites using self-signed certificates.

Choices:

  • false

  • true ← (default)

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

diff_mode

Support: full

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platform: debian

Target OS/families that can be operated against

Notes

Note

  • This module supports Debian Squeeze (version 6) as well as its successors and derivatives.

See Also

See also

ansible.builtin.deb822_repository

Add and remove deb822 formatted repositories.

Examples

- name: Add specified repository into sources list
  ansible.builtin.apt_repository:
    repo: deb http://archive.canonical.com/ubuntu hardy partner
    state: present

- name: Add specified repository into sources list using specified filename
  ansible.builtin.apt_repository:
    repo: deb http://dl.google.com/linux/chrome/deb/ stable main
    state: present
    filename: google-chrome

- name: Add source repository into sources list
  ansible.builtin.apt_repository:
    repo: deb-src http://archive.canonical.com/ubuntu hardy partner
    state: present

- name: Remove specified repository from sources list
  ansible.builtin.apt_repository:
    repo: deb http://archive.canonical.com/ubuntu hardy partner
    state: absent

- name: Add nginx stable repository from PPA and install its signing key on Ubuntu target
  ansible.builtin.apt_repository:
    repo: ppa:nginx/stable

- name: Add nginx stable repository from PPA and install its signing key on Debian target
  ansible.builtin.apt_repository:
    repo: 'ppa:nginx/stable'
    codename: trusty

- name: One way to avoid apt_key once it is removed from your distro
  block:
    - name: somerepo |no apt key
      ansible.builtin.get_url:
        url: https://download.example.com/linux/ubuntu/gpg
        dest: /etc/apt/keyrings/somerepo.asc

    - name: somerepo | apt source
      ansible.builtin.apt_repository:
        repo: "deb [arch=amd64 signed-by=/etc/apt/keyrings/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable"
        state: present

Return Values

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

Key

Description

repo

string

A source string for the repository

Returned: always

Sample: "deb https://artifacts.elastic.co/packages/6.x/apt stable main"

sources_added

list / elements=string

added in ansible-core 2.15

List of sources added

Returned: success, sources were added

Sample: ["/etc/apt/sources.list.d/artifacts_elastic_co_packages_6_x_apt.list"]

sources_removed

list / elements=string

added in ansible-core 2.15

List of sources removed

Returned: success, sources were removed

Sample: ["/etc/apt/sources.list.d/artifacts_elastic_co_packages_6_x_apt.list"]

Authors

  • Alexander Saltanov (@sashka)