ansible.builtin.yum_repository module – Add or remove YUM repositories

ansible.builtin.yum_repository module – Add or remove YUM repositories

https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/yum_repository_module.html

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name yum_repository even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.yum_repository for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis

Parameters

Attributes

Notes

Examples

Return Values

Synopsis Add or remove YUM repositories in RPM-based Linux distributions.

If you wish to update an existing repository definition use community.general.ini_file instead.

Parameters Parameter

Comments

async boolean

If set to true Yum will download packages and metadata from this repo in parallel, if possible.

In ansible-core 2.11, 2.12, and 2.13 the default value is true.

This option has been removed in RHEL 8. If you’re using one of the versions listed above, you can set this option to null to avoid passing an unknown configuration option.

This parameter is deprecated as it has been removed on systems supported by ansible-core and will be removed in ansible-core 2.22.

Choices:

false

true

attributes aliases: attr

string

The attributes the resulting filesystem object should have.

To get supported flags look at the man page for chattr on the target system.

This string should contain the attributes in the same order as the one displayed by lsattr.

The = operator is assumed as default, otherwise + or - operators need to be included in the string.

bandwidth string

Maximum available network bandwidth in bytes/second. Used with the throttle option.

If throttle is a percentage and bandwidth is 0 then bandwidth throttling will be disabled. If throttle is expressed as a data rate (bytes/sec) then this option is ignored. Default is 0 (no bandwidth throttling).

baseurl list / elements=string

URL to the directory where the yum repository’s ‘repodata’ directory lives.

It can also be a list of multiple URLs.

This, the metalink or mirrorlist parameters are required if state is set to present.

cost string

Relative cost of accessing this repository. Useful for weighing one repo’s packages as greater/less than any other.

countme boolean

added in ansible-core 2.18

Whether a special flag should be added to a randomly chosen metalink/mirrorlist query each week. This allows the repository owner to estimate the number of systems consuming it.

Choices:

false

true

deltarpm_metadata_percentage string

When the relative size of deltarpm metadata vs pkgs is larger than this, deltarpm metadata is not downloaded from the repo. Note that you can give values over 100, so 200 means that the metadata is required to be half the size of the packages. Use 0 to turn off this check, and always download metadata.

This parameter is deprecated as it has no effect with dnf as an underlying package manager and will be removed in ansible-core 2.22.

deltarpm_percentage string

When the relative size of delta vs pkg is larger than this, delta is not used. Use 0 to turn off delta rpm processing. Local repositories (with file://baseurl) have delta rpms turned off by default.

description string

A human-readable string describing the repository. This option corresponds to the name property in the repo file.

This parameter is only required if state=present.

enabled boolean

This tells yum whether or not use this repository.

Yum default value is true.

Choices:

false

true

enablegroups boolean

Determines whether yum will allow the use of package groups for this repository.

Yum default value is true.

Choices:

false

true

exclude aliases: excludepkgs

list / elements=string

List of packages to exclude from updates or installs. This should be a space separated list. Shell globs using wildcards (for example * and ?) are allowed.

The list can also be a regular YAML array.

excludepkgs alias was added in ansible-core 2.18.

failovermethod string

roundrobin randomly selects a URL out of the list of URLs to start with and proceeds through each of them as it encounters a failure contacting the host.

priority starts from the first baseurl listed and reads through them sequentially.

Choices:

“roundrobin”

“priority”

file string

File name without the .repo extension to save the repo in. Defaults to the value of name.

gpgcakey string

A URL pointing to the ASCII-armored CA key file for the repository.

This parameter is deprecated as it has no effect with dnf as an underlying package manager and will be removed in ansible-core 2.22.

gpgcheck boolean

Tells yum whether or not it should perform a GPG signature check on packages.

No default setting. If the value is not set, the system setting from /etc/yum.conf or system default of false will be used.

Choices:

false

true

gpgkey list / elements=string

A URL pointing to the ASCII-armored GPG key file for the repository.

It can also be a list of multiple URLs.

group string

Name of the group that should own the filesystem object, as would be fed to chown.

When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership.

http_caching string

Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does.

all means that all HTTP downloads should be cached.

packages means that only RPM package downloads should be cached (but not repository metadata downloads).

none means that no HTTP downloads should be cached.

This parameter is deprecated as it has no effect with dnf as an underlying package manager and will be removed in ansible-core 2.22.

Choices:

“all”

“packages”

“none”

include string

Include external configuration file. Both, local path and URL is supported. Configuration file will be inserted at the position of the include= line. Included files may contain further include lines. Yum will abort with an error if an inclusion loop is detected.

includepkgs list / elements=string

List of packages you want to only use from a repository. This should be a space separated list. Shell globs using wildcards (for example * and ?) are allowed. Substitution variables (for example $releasever) are honored here.

The list can also be a regular YAML array.

ip_resolve string

Determines how yum resolves host names.

4 or IPv4 - resolve to IPv4 addresses only.

6 or IPv6 - resolve to IPv6 addresses only.

Choices:

“4”

“6”

“IPv4”

“IPv6”

“whatever”

keepalive boolean

This tells yum whether or not HTTP/1.1 keepalive should be used with this repository. This can improve transfer speeds by using one connection when downloading multiple files from a repository.

This parameter is deprecated as it has no effect with dnf as an underlying package manager and will be removed in ansible-core 2.22.

Choices:

false

true

metadata_expire string

Time (in seconds) after which the metadata will expire.

Default value is 6 hours.

metadata_expire_filter string

Filter the metadata_expire time, allowing a trade of speed for accuracy if a command doesn’t require it. Each yum command can specify that it requires a certain level of timeliness quality from the remote repos. from “I’m about to install/upgrade, so this better be current” to “Anything that’s available is good enough”.

never - Nothing is filtered, always obey metadata_expire.

read-only:past - Commands that only care about past information are filtered from metadata expiring. Eg. yum history info (if history needs to lookup anything about a previous transaction, then by definition the remote package was available in the past).

read-only:present - Commands that are balanced between past and future. Eg. yum list yum.

read-only:future - Commands that are likely to result in running other commands which will require the latest metadata. Eg. yum check-update.

Note that this option does not override yum clean expire-cache.

This parameter is deprecated as it has no effect with dnf as an underlying package manager and will be removed in ansible-core 2.22.

Choices:

“never”

“read-only:past”

“read-only:present”

“read-only:future”

metalink string

Specifies a URL to a metalink file for the repomd.xml, a list of mirrors for the entire repository are generated by converting the mirrors for the repomd.xml file to a baseurl.

This, the baseurl or mirrorlist parameters are required if state is set to present.

mirrorlist string

Specifies a URL to a file containing a list of baseurls.

This, the baseurl or metalink parameters are required if state is set to present.

mirrorlist_expire string

Time (in seconds) after which the mirrorlist locally cached will expire.

Default value is 6 hours.

This parameter is deprecated as it has no effect with dnf as an underlying package manager and will be removed in ansible-core 2.22.

mode any

The permissions the resulting filesystem object should have.

For those used to /usr/bin/chmod remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, ‘644’ or ‘1777’) so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, 0755) works sometimes, but can fail in loops and some other circumstances.

Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results.

As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, u+rwx or u=rw,g=r,o=r).

If mode is not specified and the destination filesystem object does not exist, the default umask on the system will be used when setting the mode for the newly created filesystem object.

If mode is not specified and the destination filesystem object does exist, the mode of the existing filesystem object will be used.

Specifying mode is the best way to ensure filesystem objects are created with the correct permissions. See CVE-2020-1736 for further details.

module_hotfixes boolean

added in ansible-core 2.11

Disable module RPM filtering and make all RPMs from the repository available. The default is null.

Choices:

false

true

name string / required

Unique repository ID. This option builds the section name of the repository in the repo file.

This parameter is only required if state is set to present or absent.

owner string

Name of the user that should own the filesystem object, as would be fed to chown.

When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership.

Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion.

password string

Password to use with the username for basic authentication.

priority string

Enforce ordered protection of repositories. The value is an integer from 1 to 99.

This option only works if the YUM Priorities plugin is installed.

protect boolean

Protect packages from updates from other repositories.

This parameter is deprecated as it has no effect with dnf as an underlying package manager and will be removed in ansible-core 2.22.

Choices:

false

true

proxy string

URL to the proxy server that yum should use. Set to none to disable the global proxy setting.

proxy_password string

Password for this proxy.

proxy_username string

Username to use for proxy.

repo_gpgcheck boolean

This tells yum whether or not it should perform a GPG signature check on the repodata from this repository.

Choices:

false

true

reposdir path

Directory where the .repo files will be stored.

Default: “/etc/yum.repos.d”

retries string

Set the number of times any attempt to retrieve a file should retry before returning an error. Setting this to 0 makes yum try forever.

s3_enabled boolean

Enables support for S3 repositories.

This option only works if the YUM S3 plugin is installed.

Choices:

false

true

selevel string

The level part of the SELinux filesystem object context.

This is the MLS/MCS attribute, sometimes known as the range.

When set to _default, it will use the level portion of the policy if available.

serole string

The role part of the SELinux filesystem object context.

When set to _default, it will use the role portion of the policy if available.

setype string

The type part of the SELinux filesystem object context.

When set to _default, it will use the type portion of the policy if available.

seuser string

The user part of the SELinux filesystem object context.

By default it uses the system policy, where applicable.

When set to _default, it will use the user portion of the policy if available.

skip_if_unavailable boolean

If set to true yum will continue running if this repository cannot be contacted for any reason. This should be set carefully as all repos are consulted for any given command.

Choices:

false

true

ssl_check_cert_permissions boolean

Whether yum should check the permissions on the paths for the certificates on the repository (both remote and local).

If we can’t read any of the files then yum will force skip_if_unavailable to be true. This is most useful for non-root processes which use yum on repos that have client cert files which are readable only by root.

This parameter is deprecated as it has no effect with dnf as an underlying package manager and will be removed in ansible-core 2.22.

Choices:

false

true

sslcacert aliases: ca_cert

string

Path to the directory containing the databases of the certificate authorities yum should use to verify SSL certificates.

sslclientcert aliases: client_cert

string

Path to the SSL client certificate yum should use to connect to repos/remote sites.

sslclientkey aliases: client_key

string

Path to the SSL client key yum should use to connect to repos/remote sites.

sslverify aliases: validate_certs

boolean

Defines whether yum should verify SSL certificates/hosts at all.

Choices:

false

true

state string

State of the repo file.

Choices:

“absent”

“present” ← (default)

throttle string

Enable bandwidth throttling for downloads.

This option can be expressed as a absolute data rate in bytes/sec. An SI prefix (k, M or G) may be appended to the bandwidth value.

timeout string

Number of seconds to wait for a connection before timing out.

ui_repoid_vars string

When a repository id is displayed, append these yum variables to the string if they are used in the baseurl/etc. Variables are appended in the order listed (and found).

This parameter is deprecated as it has no effect with dnf as an underlying package manager and will be removed in ansible-core 2.22.

unsafe_writes boolean

Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object.

By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner.

This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes).

IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption.

Choices:

false ← (default)

true

username string

Username to use for basic authentication to a repo or really any url.

Attributes Attribute

Support

Description

check_mode full

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

diff_mode full

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

platform Platform: rhel

Target OS/families that can be operated against

Notes Note

All comments will be removed if modifying an existing repo file.

Section order is preserved in an existing repo file.

Parameters in a section are ordered alphabetically in an existing repo file.

The repo file will be automatically deleted if it contains no repository.

When removing a repository, beware that the metadata cache may still remain on disk until you run yum clean all. Use a notification handler for this.

The params parameter was removed in Ansible 2.5 due to circumventing Ansible’s parameter handling

Examples

• name: Add repository ansible.builtin.yum_repository: name: epel description: EPEL YUM repo baseurl: https://download.fedoraproject.org/pub/epel/$releasever/$basearch/

• name: Add multiple repositories into the same file (1/2) ansible.builtin.yum_repository: name: epel description: EPEL YUM repo file: external_repos baseurl: https://download.fedoraproject.org/pub/epel/$releasever/$basearch/ gpgcheck: no

• name: Add multiple repositories into the same file (2/2) ansible.builtin.yum_repository: name: rpmforge description: RPMforge YUM repo file: external_repos baseurl: http://apt.sw.be/redhat/el7/en/$basearch/rpmforge mirrorlist: http://mirrorlist.repoforge.org/el7/mirrors-rpmforge enabled: no

Handler showing how to clean yum metadata cache

• name: yum-clean-metadata ansible.builtin.command: yum clean metadata

Example removing a repository and cleaning up metadata cache

• name: Remove repository (and clean up left-over metadata) ansible.builtin.yum_repository: name: epel state: absent notify: yum-clean-metadata

• name: Remove repository from a specific repo file ansible.builtin.yum_repository: name: epel file: external_repos state: absent Return Values Common return values are documented here, the following are the fields unique to this module:

Key

Description

repo string

repository name

Returned: success

Sample: “epel”

state string

state of the target, after execution

Returned: success

Sample: “present”

Authors Jiri Tyr (@jtyr)

Collection links Issue Tracker Repository (Sources) Communication © Copyright Ansible project contributors. Last updated on Jan 12, 2026.