Update or upgrade WHMCS safely (automatic and manual)

WHMCS releases feature versions, maintenance releases and security patches. Staying current protects your customers' data and keeps payment gateways working. Updating is usually quick, but a little preparation avoids most problems with custom themes and third-party modules.

Before you start

• Read the release notes for your target version, especially the PHP requirements and breaking changes.
• Check that your third-party modules, addons and themes support the new version.
• Pick a quiet time; the client area is briefly in maintenance during the upgrade.

Back up first

1. Back up the database: export it from phpMyAdmin or with mysqldump, or use your control panel's backup tool.
2. Back up all WHMCS files, including configuration.php, custom templates, hooks, modules and language overrides.
3. Keep the backups somewhere other than the WHMCS server.

Check PHP compatibility

New WHMCS versions often require a newer PHP version and the matching ionCube Loader. If you need to change PHP, do it after the files are updated but before visiting the admin area, or follow the release notes' order. Changing PHP in cPanel's MultiPHP Manager takes effect immediately.

Option A: Automatic Updater

1. Go to Utilities → Update WHMCS.
2. Click Check for Updates. Choose the update channel (Stable is recommended for production).
3. Configure the Staging Directory (a writable folder outside the web root) if asked.
4. Confirm you have a backup and click Update Now.
5. WHMCS downloads, applies the files and runs the database upgrade.

Option B: Manual update

1. Download the full release ZIP (or the patch set for incremental releases) from your WHMCS client area.
2. Extract it locally and delete configuration.php.new and, if you renamed the admin folder, rename the new admin folder to match.
3. Upload and overwrite the files in your WHMCS directory.
4. Visit https://billing.example.com/install/install.php and follow the upgrade steps.
5. Delete the install folder when finished.

After updating

• Log in to the admin area and confirm the new version in the footer.
• Check Utilities → System → System Health for warnings.
• Empty the template cache: Utilities → System → System Cleanup.
• Place a test order, open a test ticket, and check a payment gateway in test mode.
• Confirm the cron still runs in Utilities → Automation Status; a PHP change can break the cron command.
• Compare copied templates in your child theme with the new originals.

Troubleshooting

• ionCube error after update: the new files require a newer ionCube Loader or PHP version.
• Automatic update fails on file permissions: the web server user cannot write to some files. Fix ownership or use the manual method.
• Blank admin page: an incompatible addon. Rename its folder in modules/addons to disable it, then update or remove it.
• Database upgrade error: restore the database backup and the old files, then contact WHMCS support with the error.

Next steps

• Review the security checklist.
• Automate WHMCS database backups.
• Keep your theme upgrade-safe.