How to Upgrade WHMCS? 

Keeping WHMCS updated is essential for better security, improved performance, bug fixes, and compatibility with the latest server environments and payment gateways. WHMCS offers two ways to upgrade: the built-in Automatic Updater in the Admin Area, and a manual upgrade on the server. Always review the official WHMCS release notes and system requirements before upgrading, since steps can vary by version. 

Why Keep WHMCS Updated 

• Security – each release includes fixes for known vulnerabilities 
• Stability – bug fixes and performance improvements for core services 
• Compatibility – support for newer PHP versions, payment gateways, and server software 
• New Features – access to the latest tools for managing clients, billing, and support 

Choosing Between Automatic and Manual Upgrades 

• Automatic Updater – recommended for most installations; handles file replacement, database updates, and compatibility checks with minimal manual work 
• Manual upgrade – recommended for advanced users, when the server can’t meet the Automatic Updater’s requirements, when managing multiple installations, or when full control over each step is needed 

Method 1: Automatic WHMCS Upgrade 

System Requirements 

• PHP memory limit of at least 128 MB 
• At least 250 MB of free disk space 
• PHP allow_url_fopen setting enabled 
• PHP max_execution_time of 60 seconds or more 
• PHP Zip extension or the proc_open function enabled 

• PHP open_basedir disabled, or configured to include the WHMCS document root 

Steps to Update 

Go to Utilities → Update WHMCS and click Check for Updates.

Click Configure Update Settings and set the Update Channel to Stable.

Review the release notes for the target WHMCS version.

Click Download Database Backup before proceeding with the update.

Review any customizations flagged as affected by the update.

Click Update Now and wait for the process to complete without closing the browser.

Log in as both an admin and a client to confirm tickets, orders, and product pages are working correctly.

Manually trigger the cron job once to confirm automation, invoicing, and renewal emails are running without errors.

Re-verify your WHMCS license key under Setup → General Settings if you see a licensing warning after the update.

If the update menu is missing, go to Setup → Staff Management → Administrator Roles and enable the Update WHMCS permission for your role.

Method 2: Manual Upgrade on the Server 

Before starting, confirm you have SSH access to the server, access to the WHMCS installation directory, a valid WHMCS license to download the latest release, and account-level permissions for file operations. 

The example below uses generic placeholder values. Replace youraccount, yourdomain.com, and admindir with the real values for your own server. 

Step 1: Prepare the Server and Take a Backup 

• Identify the WHMCS installation directory (confirmed by the presence of configuration.php) 

• Enable Maintenance Mode from Setup → General Settings → Maintenance Mode so customers can’t access the site mid-upgrade 

• Take a full copy of the existing installation folder before changing anything 

Back up the entire installation folder to a safe, timestamped copy: 

cd /home/youraccount/ 
cp -vR public_html/ public_html.old 

Step 2: Back Up the Database 

• Database credentials are stored inside configuration.php in the WHMCS installation folder 

• Export a full database backup before making any further changes 

View the database details in configuration.php: 

cat public_html.old/configuration.php 

Export the database using mysqldump  

mysqldump whmcs_db_name > whmcs_db_backup_old.sql 

Step 3: Download and Upload the New Release 

• Download the latest full-release WHMCS package from the official client area (you must be logged in as a client to access the download) 

• Upload the downloaded package to the server using SCP or FTP 

 Step 4: Extract and Copy the New Files 

• Before extracting, confirm there is no leftover whmcs/ folder from a previous attempt 

• Extract the package, then copy its contents into the live installation folder 

• Using a force-copy command skips confirmation prompts, so double-check the source and destination paths first 

Confirm no old extraction folder exists, then extract and copy the new files in: 

cd /home/youraccount/ 
ls -d whmcs/ 2>/dev/null || echo “no leftover folder, safe to continue” 
unzip whmcs_vXXX_full.zip 
cp -Rv whmcs/* ./public_html/ 

Step 5: Rename the Admin Directory and Fix Permissions 

• If you use a renamed admin folder for security, move it aside and rename the new admin folder to match 

• Copy over any .htaccess authentication rules from the old admin folder to the new one 

• Confirm the AuthUserFile path referenced in .htaccess is still accessible after the rename 

• Reset file ownership so the web server user owns all the new files 

Rename the admin directory (replace admindir with your own custom admin path): 

cd /home/youraccount/public_html/ 
mv admindir/ admindir.old 
mv admin/ admindir 

If present, copy the old .htaccess rules into the new admin folder, for example: 

AuthName “Admins Only” 
AuthUserFile “/home/youraccount/.htpasswds/admindir/passwd” 
AuthType Basic 
require valid-user 

Fix ownership so the account user owns all files: 

chown -R youraccount.youraccount public_html/* 

Step 6: Run the Upgrade Wizard 

• Open the WHMCS installer in a browser — it will detect the existing installation and redirect you into the upgrade wizard 

• Accept the WHMCS End User License Agreement and follow the on-screen steps to upgrade the database 

• Do not close the browser or interrupt the process while the database upgrade is running 

Open the installer at: 

https://yourdomain.com/install/install.php

• Disable Maintenance Mode 

• Confirm core functions work: client login, ticket submission, orders, and product pages 

• Manually trigger the cron job once to confirm automation, invoicing, and renewal emails are running without errors 

• Re-verify your WHMCS license key is active if a licensing warning appears after the update 

Troubleshooting Common WHMCS Upgrade Issues 

Database Upgrade Errors 

• Check the WHMCS error logs for the specific failure 
• Restore the database backup if the upgrade cannot complete 
• Verify database user permissions are correct 

Conclusion 

Upgrading WHMCS on a production server requires careful preparation, whether you use the Automatic Updater or a manual upgrade. Both approaches depend on complete backups, a clear understanding of any customizations, and thorough testing afterward. For most installations, the Automatic Updater is the safer and faster option — manual upgrades remain useful for advanced users and custom server setups. Keep this checklist handy so your next upgrade goes just as smoothly.