WHMCS Upgrade Guide: How to Update WHMCS to a New Version

To update WHMCS on a self-hosted install, use the built-in Automatic Updater at Utilities > Update WHMCS. Before you click Update Now, read the release notes, check the system requirements for the target version, run the update on a private copy, and back up the database and the whole WHMCS directory, including configuration.php. Manual updates by browser or command line are for advanced users.

Where is the built-in WHMCS updater?

It is at Utilities > Update WHMCS in the Admin Area. WHMCS checks for new releases by itself through the system cron and shows a notice when one is available. The Check for Updates button forces a check, and when the page says "An update is available", Update Now starts the process.

Two admin role permissions are involved: Update WHMCS to run an update, and Modify Update Configuration to change the options behind the Configure Update Settings button. WHMCS Cloud is updated by WHMCS, so this guide is for self-hosted installs. The reference page is Updating WHMCS.

Which WHMCS update channel should you choose?

Choose Stable on a production install. The channel sets the least stable kind of release that the updater will offer you.

To change it, open Utilities > Update WHMCS, click Configure Update Settings, select the channel and save. To patch a Long Term Support install, select Current Version, click Check for Updates and update. Switch back to Stable afterwards if you want to see newer versions again.

What should you check before a WHMCS upgrade?

Check six things, in the order given on the official Prepare to Update WHMCS page.

1. Release notes for the target version and for every version in between.
2. System requirements for the target version and each intermediate one.
3. Customizations. Custom themes and order form templates must sit in their own directories, because an update overwrites the default ones.
4. A test run on a copy. WHMCS gives one free development license for each active license bought directly from it. If you bought through a reseller, you have to buy one. The copy must be private, and Disable Email Sending should be on in the Mail tab of General Settings.
5. Backups of the database and the entire WHMCS directory.
6. MySQL permissions. The update creates and alters tables, so the database user needs its full privileges while it runs, including ALTER, CREATE, DROP and INDEX if you removed them for daily use.

The Automatic Updater adds requirements of its own:

• A PHP memory limit of at least 128 MB and at least 250 MB of free disk space.
• allow_url_fopen enabled and max_execution_time of 60 seconds or more.
• The PHP Zip extension or the proc_open function.
• open_basedir disabled. If it cannot be, it must include the WHMCS document root, /dev/null and any directories you moved outside the document root.

Which PHP and ionCube versions does a WHMCS upgrade need?

The answer is on the System Requirements page for the version you are moving to, and it changes with releases. When I read the WHMCS 9.0 page on 10 October 2026, it listed PHP 8.2 or 8.3, with ionCube Loader 13.0.2 or higher for PHP 8.2 and 14.4.0 or higher for PHP 8.3.

• Old installs. Updating through several versions can force a stop in the middle to change PHP. The documentation page Updating Through EOL Versions lists the PHP and ionCube Loader pairs for older releases.
• Encoded modules. The report at Utilities > System > PHP Version Compatibility lists ionCube-encoded files that may not decode under a given PHP version. It checks decoding only, not PHP syntax.
• Unknown results. If a file shows Encoding Compatibility Unknown, ask its vendor. With no compatible release, the documented choices are to remove the module or to wait before you upgrade PHP.

How do you back up WHMCS before updating?

Back up the database and the entire WHMCS directory, and confirm that configuration.php is in the copy. That file holds the encryption hash. Without it, the passwords and card data stored in the database cannot be decrypted.

• The updater shows a Download Database Backup button before it starts.
• Utilities > System > Database Status has a manual download.
• If automated backups are set up at Configuration > System Settings > Database Backups, php -q cron.php do --DatabaseBackup runs that task on demand.
• For the files, I archive the whole directory plus anything that was moved outside the web root, such as the crons folder.

The Database Backups page warns that the email backup option may fail on large databases. A backup you have never restored is unproven, so I restore the dump into the test copy during step 4.

How do you upgrade WHMCS to a new version?

With the Automatic Updater, it takes six steps.

1. Go to Utilities > Update WHMCS and click Update Now.
2. Confirm the version it will install.
3. Click Download Database Backup.
4. If WHMCS lists customized core files, copy them somewhere safe. The update overwrites them.
5. Click Begin Update. The documentation says this typically takes 20 to 60 seconds.
6. Wait for the success message.

An update replaces the core files, the language files in lang and admin/lang, the default templates in templates/twenty-one, templates/six and templates/orderforms, and the modules that WHMCS supplies.

There are two manual routes, which WHMCS only recommends for advanced users. In the browser, you upload the full release over the install, open /install/install.php, continue to "I have a backup, start the upgrade", and delete the install directory afterwards. On the command line, you copy the files in and run this:

php -f path/to/whmcs/install/bin/installer.php -- -u

With either manual route, a renamed admin directory and a moved crons folder need the new files copied to their custom locations.

Does WHMCS have auto update?

Yes, in two senses. The Automatic Updater above is automatic once an admin starts it. Updates that apply on a schedule with nobody logged in are a separate feature, Unattended Automatic Updates, documented for WHMCS 9.1. The documentation home page marked 9.1 as Beta when I read it.

• It applies maintenance releases only, which change the last segment of the version number. Major and minor upgrades stay manual.
• The system cron does the work. If the cron is not running, neither are unattended updates.
• Before applying, it backs up only the files it will replace. It does not back up the database.
• If an update fails after it has started, WHMCS restores those files. It tries a release up to three times.
• The user WHMCS runs as needs read, write and execute permissions on the whole install directory.

I would keep scheduled database backups running regardless.

What should you check after a WHMCS update?

Check the paths that bring in money first. The documentation suggests logging in as an admin and as a client, viewing products, submitting a support ticket and placing an order.

Then watch Configuration > System Health for the next 24 hours, and look at Utilities > Automation Status after the next daily cron run. If pages look broken, the documented cause in most cases is an outdated custom template. Compare it with the template changes in the release notes, then empty the template cache at Utilities > System > System Cleanup.

What do you do when a WHMCS update fails?

Read the error before you change anything, because the output names the cause. The Update Failed Errors page lists the common ones.

The updater's own log is the tblupdatelog database table. If you cannot finish the update, restore the database, the files and configuration.php from the backup you took before starting.

There are also times not to update yet:

• A module you depend on has no release for the target version or its PHP.
• You have not run the update on a copy.
• The only way to get the version is the Beta or Release Candidate channel, and the install is production.

If the update comes with a server move, my guide on how to migrate WHMCS covers that part. If you want someone else to run it, I do upgrades under WHMCS support and maintenance and repair failed ones as hourly WHMCS developer work, after a free scoping call of about 30 minutes and a written quote within one business day.

Last reviewed 10 October 2026. Disclosure: I am a freelance WHMCS developer and I sell WHMCS upgrades and maintenance, so I am not neutral. WHMCS sells an upgrade service of its own. I am CTO at ElySpace, a freelance developer for Marmaids LLC, and founder of WHMCSPilot and MagizAI. Paths, settings and version numbers come from the WHMCS documentation as I read it on that date.