community.general.dnf_versionlock module – Locks package versions in dnf based systems


This module is part of the community.general collection (version 5.4.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.dnf_versionlock.

New in version 4.0.0: of community.general


  • Locks package versions using the versionlock plugin in dnf based systems. This plugin takes a set of name and versions for packages and excludes all other versions of those packages. This allows you to for example protect packages from being updated by newer versions. The state of the plugin that reflects locking of packages is the locklist.


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

  • dnf

  • dnf-plugin-versionlock





list / elements=string

Package name spec to add or exclude to or delete from the locklist using the format expected by the dnf repoquery command.

This parameter is mutually exclusive with state=clean.

Default: []



Do not resolve package name specs to NEVRAs to find specific version to lock to. Instead the package name specs are used as they are. This enables locking to not yet available versions of the package.


  • no ← (default)

  • yes



Whether to add (present or excluded) to or remove (absent or clean) from the locklist.

present will add a package name spec to the locklist. If there is a installed package that matches, then only that version will be added. Otherwise, all available package versions will be added.

excluded will add a package name spec as excluded to the locklist. It means that packages represented by the package name spec will be excluded from transaction operations. All available package versions will be added.

absent will delete entries in the locklist that match the package name spec.

clean will delete all entries in the locklist. This option is mutually exclusive with name.


  • absent

  • clean

  • excluded

  • present ← (default)



  • The logics of the versionlock plugin for corner cases could be confusing, so please take in account that this module will do its best to give a check_mode prediction on what is going to happen. In case of doubt, check the documentation of the plugin.

  • Sometimes the module could predict changes in check_mode that will not be such because versionlock concludes that there is already a entry in locklist that already matches.

  • In an ideal world, the versionlock plugin would have a dry-run option to know for sure what is going to happen. So far we have to work with a best guess as close as possible to the behaviour inferred from its code.

  • For most of cases where you want to lock and unlock specific versions of a package, this works fairly well.

  • Supports check_mode.


- name: Prevent installed nginx from being updated
    name: nginx
    state: present

- name: Prevent multiple packages from being updated
      - nginx
      - haproxy
    state: present

- name: Remove lock from nginx to be updated again
    package: nginx
    state: absent

- name: Exclude bind 32:9.11 from installs or updates
    package: bind-32:9.11*
    state: excluded

- name: Keep bash package in major version 4
    name: bash-0:4.*
    raw: true
    state: present

- name: Delete all entries in the locklist of versionlock
    state: clean

Return Values

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




list / elements=string

Locklist after module execution.

Returned: success and (not check mode or state is clean)

Sample: [“bash-0:4.4.20-1.el8_4.*”]


list / elements=string

Locklist before module execution.

Returned: success

Sample: [“bash-0:4.4.20-1.el8_4.*”, “!bind-32:9.11.26-4.el8_4.*”]


list / elements=string

Package name specs meant to be added by versionlock.

Returned: success

Sample: [“bash”]


list / elements=string

Package name specs meant to be deleted by versionlock.

Returned: success

Sample: [“bind”]


  • Roberto Moreda (@moreda)