Complete Guide to the rpm.versions System in cPanel & WHM (How to Override Package States – Versions 110 to Latest)

1. Introduction

The rpm.versions system in cPanel & WHM manages the installation, removal, and updates of RPM packages on Red Hat–based systems (AlmaLinux, Rocky, CentOS, CloudLinux) and DEB packages on Ubuntu. This system ensures that cPanel maintains the correct versions of required packages.

The main configuration file is located at:

/usr/local/cpanel/etc/rpm.versions

Important: This file is overwritten during every cPanel update and must never be edited directly.

To override cPanel’s defaults, use the following directory:

/var/cpanel/rpm.versions.d/

Files in this directory (with the .versions extension, written in YAML) take priority over cPanel’s defaults.

2. File Types in /var/cpanel/rpm.versions.d/

File	Description	Priority	Recommendation
local.versions	Admin‑controlled override file	Highest	Only file you should manually edit
*.versions (third‑party)	Plugin or vendor override files	Medium	May conflict if multiple plugins modify same target
/usr/local/cpanel/etc/rpm.versions	Default cPanel configuration	Lowest	Read‑only

3. Structure of a .versions File (YAML)

All override files use YAML format. YAML is whitespace‑sensitive, so indentation must be exact.

file_format:
  version: 2

install_targets: {}
rpm_groups: {}
deferred_settings: {}
deferred_optional: {}
rpm_locations: {}
srpm_sub_packages: {}
srpm_versions: {}

target_settings:
  pure-ftpd: unmanaged   # Example override

url_templates: {}

The most important section is target_settings, where you override package states.

4. Target States

State	Description	Common Use	Warning
installed	cPanel ensures the package is installed	Default for most services	—
uninstalled	cPanel removes the package	When you do not want the service	—
unmanaged	cPanel ignores the package entirely	When you manage the service manually	Dangerous: may break upgrades or UI

Warnings About unmanaged:

Package will not auto‑update.
FTP UI may break if FTP is unmanaged.
Unmanaged MySQL/MariaDB can block future upgrades.

5. The update_local_rpm_versions Script

Because YAML is sensitive, cPanel provides a helper script to safely edit override files.

Add or modify a target:

/usr/local/cpanel/scripts/update_local_rpm_versions --edit target_settings.pure-ftpd unmanaged

Remove an override:

/usr/local/cpanel/scripts/update_local_rpm_versions --del target_settings.pure-ftpd

Apply changes:

/usr/local/cpanel/scripts/check_cpanel_pkgs --fix

6. Practical Examples

Disable Pure‑FTPd (set to unmanaged):

/usr/local/cpanel/scripts/update_local_rpm_versions --edit target_settings.pure-ftpd unmanaged
/usr/local/cpanel/scripts/update_local_rpm_versions --edit target_settings.proftpd unmanaged
/usr/local/cpanel/scripts/check_cpanel_pkgs --fix

Remove ClamAV (set to uninstalled):

/usr/local/cpanel/scripts/update_local_rpm_versions --edit target_settings.clamav uninstalled
/usr/local/cpanel/scripts/check_cpanel_pkgs --fix

Restore cPanel defaults:

/usr/local/cpanel/scripts/update_local_rpm_versions --del target_settings.clamav
/usr/local/cpanel/scripts/check_cpanel_pkgs --fix

7. Golden Rules

Never edit /usr/local/cpanel/etc/rpm.versions — it resets on update.
Third‑party plugins may conflict if they override the same target.
local.versions has the highest priority and overrides everything.
Be extremely careful with unmanaged — it can break upgrades or UI components.

8. Conclusion

The rpm.versions system is a powerful mechanism that controls how cPanel manages system packages. By using override files in /var/cpanel/rpm.versions.d/ and the update_local_rpm_versions script, you can safely customize package behavior without risking conflicts during updates. Always follow best practices and avoid unmanaged states unless absolutely necessary.