Knowing how to update WHMCS safely is one of those skills that saves you a bad weekend. Updates bring security fixes, new features and compatibility with newer PHP versions. They can also break custom themes, modules and cron jobs if you rush. This guide gives you a calm, repeatable checklist: what to do before, during and after an update, so your billing system keeps running and your clients never notice.
It applies to self-hosted WHMCS. WHMCS Cloud updates automatically, so you won’t need most of these steps.
Why You Shouldn’t Put Off a WHMCS Update
Staying on an old version is tempting when everything works. The risk grows quietly, though. Old versions miss security fixes, so known problems stay open on your server. Newer PHP versions and server software can stop supporting your old release. And the further behind you fall, the bigger and riskier each update becomes. Small, regular updates are easier than one huge jump after years.
Updating is also part of good WHMCS security. Many successful attacks use bugs that were already fixed in a newer release.
Before You Update: The Preparation Checklist
The official WHMCS update preparation guide lists these steps. Don’t skip any of them.
1. Read the Release Notes
Read the notes for your target version and for every version in between. They list new features, changes, removed features and template changes. If you’re jumping several versions, the intermediate notes matter, because a change deprecated in one release may be removed in the next.
2. Check System Requirements
Confirm your server meets the requirements for the target version and each version along the way. The most common blocker is the PHP version, so check this before you start rather than after a failed update.
3. Review Your Customizations
Updates can overwrite changes made to default files. To stay safe:
- Keep custom system themes and order form templates in their own folders, never inside the default ones. Our guide to WHMCS client area customization shows how a child theme survives updates.
- Use override files wherever WHMCS supports them.
- Consider tracking your themes and templates in Git, so you can see exactly what changed.
- Check the language string changes in each release and update your custom language files to match.
4. Test on a Copy First
Build a test installation that mirrors production as closely as you can, then run the update there first. WHMCS offers a free testing license to customers who bought directly from them. A test run shows you which hooks, modules and templates break while nobody is waiting on them. If you use custom hooks or third-party modules, this step is where you find problems.
5. Back Up Everything
Back up both the WHMCS database and the entire WHMCS directory. Store the copies somewhere other than the server being updated. This is the step that turns a disaster into an inconvenience, because you can put everything back exactly as it was.
6. Confirm Database Permissions
The database user needs full permissions during an update, because the process creates and alters tables. If you’ve restricted privileges for security, raise them for the update and lower them again afterward.
Running the Update
WHMCS recommends the Automatic Updater, found in the admin area under Utilities, then Update WHMCS. It downloads the new version, applies it and runs the database changes for you. The command-line and manual browser methods exist, but they’re meant for advanced users.
- Pick a quiet time, such as late at night, when few clients are logged in.
- Confirm your backups finished and you can open the files.
- Open Utilities, then Update WHMCS, and follow the prompts.
- Let it finish. Don’t close the page or restart services halfway through.
After the Update: Check Everything
An update that finishes without errors isn’t automatically a good update. Spend ten minutes testing the paths your clients use:
- Log in as an admin and as a client.
- View products and the order form.
- Submit a support ticket.
- Place a test order, ideally for a product that triggers automatic provisioning.
- Check any custom module pages, such as your client forum.
Then keep an eye on the alerts under Configuration, then System Health, for the next 24 hours. Problems often show up there first.
Don’t Forget Cron Files and Permissions
Two easy-to-miss details can quietly break your automation. First, if you’ve moved your crons folder to a private location, you must copy the updated cron files from the default location into your custom folder after each update. If you skip this, automation errors follow. Second, confirm that any custom file permissions, such as on /crons/pipe.php, are still in place. Our guide to WHMCS automation explains what those cron tasks control.
Update Your Custom Templates
If you use a custom theme, open the Template Changes section of the release notes and compare it with your copied template files. Only the templates you’ve overridden need attention, which is a good reason to override as few files as possible.
If Something Goes Wrong
Don’t panic and don’t start changing things at random. Work through these in order:
- Read the exact error message, and check System Health and the error logs.
- Temporarily switch to a default theme to see if your custom theme is the cause.
- Deactivate third-party modules and hooks one at a time.
- If the site is down and you can’t fix it quickly, restore your backup of the database and files, then try again on your test copy.
Because you backed up and tested first, restoring is a calm decision rather than a crisis.
A Simple Update Routine
- Monthly: check for new releases and read the notes.
- Security releases: test and apply promptly.
- Every update: back up, test on a copy, update, then verify.
- Keep a list of every overridden template, custom hook and third-party module, so you know what to check.
Frequently Asked Questions
How do I update WHMCS?
Use the Automatic Updater under Utilities, then Update WHMCS, after backing up your database and files and testing on a copy. WHMCS recommends it over the command-line and manual methods.
Will updating WHMCS delete my customizations?
Changes to default files can be overwritten. Customizations kept in their own child theme, override files and hook files are the safe approach, though copied templates may still need small updates.
Can I skip versions?
You can update to a newer version, but read the release notes for every version in between, because changes and removals build up across releases. Test the full jump on a copy first.
How long does a WHMCS update take?
The update itself is often quick, but plan extra time for backups, testing and the checks afterward. A careful update is better than a fast one.
Want Help With Your WHMCS Updates?
We build and maintain custom WHMCS modules and keep them compatible with current releases, so updates don’t break what you’ve added. See our WHMCS addons, or tell us what you run and we’ll help you plan the next update.
