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.versionsImportant: 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 unmanagedRemove an override:
/usr/local/cpanel/scripts/update_local_rpm_versions --del target_settings.pure-ftpdApply changes:
/usr/local/cpanel/scripts/check_cpanel_pkgs --fix6. 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.