Updating WHMCS

You can check for the most recent updates and update WHMCS quickly and easily from directly within the Admin Area.

You can access this feature at Utilities > Update WHMCS.

Checking for Updates

The system automatically checks for updates periodically. When an update becomes available, a notification will appear in the Admin Area.

You can also check for updates manually by clicking Check for Updates. You may need to do this to see recent releases prior to the next automated check.

For steps and more information, see Check for Updates.

Updating WHMCS

If you see a An update is available message, you can click Update Now to begin an automatic update.

Make certain that you have performed all of our recommended steps to prepare before initiating an upgrade.

For steps to upgrade WHMCS, see Update with the Automatic Updater.

Requirements for Automatic Updates

WHMCS has several system requirements for automatic updates:

  • A PHP memory limit of at least 128 MB.
  • At least 250 MB of free disk space.
  • The PHP allow_url_fopen setting is enabled.
  • The PHP max_execution_time setting is 60 seconds or more.
  • The PHP Zip Extension or the proc_open PHP function are enabled.
  • The PHP open_basedir setting includes the entire WHMCS document root.

Verifying the Upgrade

After the update finishes, check to ensure that WHMCS is working properly. We recommend testing all of the important features and functions in WHMCS, like logging in as a client and as an admin, viewing products, submitting support tickets, and placing new orders.

We also recommend monitoring the alert messages at Configuration () > System Health for the 24 hours following the update:

System Health

Update Settings

You can also configure settings for your update channels, set a maintenance message to display during updates, and specify the directory to use for staging update files.

Update Settings in WHMCS

Modifying the update configuration requires the Modify Update Configuration administrator role permission, which is separate from the Update WHMCS permission.

Update Channel

You can choose the update channel for your WHMCS installation. This setting indicates the least-stable version that you want to use for updates.

For steps to update this setting, see Set the Update Channel.

WHMCS ships new updates using the following update channel options:

Update ChannelDescription
StableOnly receive Stable updates (General Availability releases) to your installation.
We recommend this update channel for most installations.
Current VersionOnly receive maintenance updates for the currently-installed major and minor version.
  • For example, if you are using a Long-Term Support version and we release a patch for it, this channel applies the patch but will not upgrade you to a later WHMCS version.
  • This is useful for applying minor updates and security releases (see below).
Release CandidateReceive releases after beta testing but before we release them to the Stable tier.
BetaReceive the latest versions of WHMCS as we release them to the Beta tier.
We only recommend selecting this update channel for development and testing installations.

Patch and Maintenance Release Updates

If you are on a WHMCS version that is in Long-Term Support and we issue a patch for that version, you can perform an update to apply the patch without moving to a newer WHMCS version.

To do this:

  1. Select the Current Version update channel.
  2. Click Check for Updates to refresh the available version.
  3. Proceed with your update as usual.

You may wish to change this setting back to Stable after updating to ensure that future checks display the most recent stable version.

Temporary Update Path

The temporary path allows you to stage files during an update. For security reasons, ensure that this directory is outside of the public document root, like the attachments, downloads, and templates_c directories.

  • The path must be an absolute path (for example, /home/username/tmp instead of ~/tmp).
  • The PHP user must be able to write to this path.
For steps to update this setting, see Set the Temporary Update Path.

Maintenance Message

Use this option to set a message to display to other admins and users whenever an update is in progress.

For steps to update this setting, see Set a Maintenance Message.

Update File Changes

During the update process, WHMCS will update all of the core files to ensure that WHMCS continues to work correctly. This includes updating the default templates and order forms.

Updates overwrite the following files:

  • Language Files (~/whmcs/lang and ~/whmcs/admin/lang)
  • Default Templates (~/whmcs/templates/six and ~/whmcs/templates/orderforms)
  • WHMCS-Supplied Modules (~/whmcs/modules/)
  • Core WHMCS Files

When you initiate an update at Utilities > Update WHMCS, WHMCS will scan the default template directories. You will see a warning if the scan finds any customizations that updating would overwrite.

Customizations to Open-Source Files

We provide some WHMCS files as open-source code, in order to allow customization (for example, the /aff.php file). Make certain that you back these customizations up before performing updates and restore them manually after the update is complete.

Preserving Customizations

If you have directly edited the files above, updating will overwrite your changes.

When you customize parts of WHMCS, make certain to use the recommended methods:

  • Copy the desired files if you want to customize a template. Make certain that you do not store your customizations in the default template folders.
  • Use override files if you want to customize a locale.
  • Ensure that you create a uniquely-named copy of any modules that you customize.
  • Ensure that you create override files for any changes to the shipped dist.whois.json and dist.additionalfields.php files. To avoid overwriting your customizations, you must store changes in the appropriate override files.

Common Errors

You can find the log of Automatic Updater actions in the tblupdatelog table in the WHMCS database. To troubleshoot upgrade problems, review this table for the most recent entries (the highest id values). You can use a tool like phpMyAdmin to browse the table’s contents.

You may encounter the following common update-related errors:

ErrorDescriptionRecommended Solution
WHMCS Not Installed ErrorYou may have overwritten the configuration.php file when you uploaded files during a manual upgrade.Restore the configuration.php file from your most recent backup before continuing.
Make certain that you have selected a valid Update Channel and then try againYou have not correctly configured the Update Channel setting.Configure and save the update channel setting.
For steps to update this setting, see Set the Update Channel.
Unable to connect to the WHMCS Update ServerYour server could not connect to the WHMCS update server. You may see this error while using the Automatic Updater feature or in a log file.To resolve this issue, run the following commands to check the connection:
curl -v https://releases.whmcs.com/v2/packages.json
curl -v https://pki.whmcs.com/
If the commands succeed, they will return a 200 status code. If you see a different code or another error, contact your hosting provider or system administrator.
Permissions ErrorsYou may encounter one or more permissions errors if your system’s file and directory permissions do not allow WHMCS to perform the required actions during an update. For example:
  • [WHMCS\Exception] Failed to perform early file copy during WHMCS file relocation: init.php
  • [RuntimeException] /path/to/whmcs/whmcs does not exist and could not be created.
  • failed to open stream: Permission denied
  • Apply update dry-run detected 1 permission issues
Make certain that all of your permissions settings allow WHMCS the correct access.
For more information, see File Permissions.
Bad FormattingIf you see incorrect formatting when you go to the Client Area or Admin Area, your browser may not have updated.Clear your browser cache or perform a hard refresh (Ctrl + F5) and delete the contents of the template cache directory (templates_c by default).
Down for Maintenance
Update in Progress
If, after uploading the files from a Patch Set, you see a Down for Maintenance or update in progress… message, the patch set files that you attempted to apply are not compatible with the version of WHMCS you were previously running.Download the latest Full Release version and update using the regular update process above.

Last modified: July 10, 2024