How to Move WHMCS to a New Server: the 12 Steps and What Usually Breaks

To move WHMCS to a new server, stop the cron on the old server, back up the database and configuration.php, copy the files, restore the database on a server that meets your WHMCS version’s requirements, point DNS at it, reissue the licence, update the System URL and recreate the cron. WHMCS documents it in 12 steps. Most failed moves come from three things: a lost encryption hash, a PHP or ionCube mismatch, or a cron left running on both servers.

How this was written. FluxBilling publishes this guide and sells a billing platform that competes with WHMCS and can import from it. The 12 steps, version requirements and quoted settings come from WHMCS’s own documentation for 8.13 and 9.0, read on 20 October 2026. Where we add advice of our own, we say so. This applies to self-hosted WHMCS only: WHMCS Cloud does not give you direct access to files or the database.

Before you start: what you need

• Shell access to both servers, or at least file and database access on each.
• A copy of configuration.php from the old server, stored somewhere other than the old server.
• The account that owns the licence. If you bought it from WHMCS, your WHMCS Member Area login; if from your hosting provider, a way to reach them.
• DNS access for the domain WHMCS runs on.
• A list of third-party modules and themes, because some carry their own licences tied to a domain or IP address.
• A quiet window. Our advice: pick the hour with the fewest orders, and avoid the time of day your daily automation runs (Configuration > System Settings > Automation Settings shows it).

Our advice again: lower the DNS record’s TTL to a few minutes a day ahead, so the switch in step 6 takes minutes rather than hours.

Does the new server meet WHMCS’s requirements?

Check this before copying anything. The requirements depend on the WHMCS version you run, and on 20 October 2026 three versions were supported:

WHMCS 9.1 was in beta on that date, adding PHP 8.4 support. The required PHP extensions are the same for both: cURL with SSL, GD2, IMAP, ionCube Loader, JSON, PDO and PDO_MySQL (compiled with mysqlnd), plus a recommended list including BC Math, GMP, Intl, mbstring, OpenSSL and SOAP.

Our advice: do not upgrade WHMCS and move servers in the same window. Move first, on the same WHMCS version and a PHP version it supports, confirm everything works, then upgrade. If something breaks, you will know which change caused it.

The 12 steps to move WHMCS

These are WHMCS’s steps in its own order, each with the detail that tends to be skipped.

1. Disable the WHMCS cron on the old server. Remove or comment out the cron job so automation cannot create invoices, send reminders or suspend services while you copy. If both servers run the cron even for an hour, customers can receive duplicate emails and invoices.
2. Back up the database. Download one from Utilities > System > Database Status, run php -q cron.php do --DatabaseBackup, or use your own mysqldump. Our advice: take the dump after step 1, so nothing writes to the database after it.
3. Check the system requirements on the new server, as in the table above.
4. Transfer the files. Copy the whole WHMCS directory, plus any directories you moved outside it: attachments, downloads, the templates_c compile directory and the crons directory if you relocated it. Keep the writable directories writable for the PHP user.
5. Restore the database and edit configuration.php. WHMCS suggests phpMyAdmin; the command line is fine too. Update $db_host, $db_name, $db_username and $db_password. If the file defines absolute paths such as $attachments_dir, $downloads_dir, $templates_compiledir or $crons_dir, change them to the new server’s paths. Leave $cc_encryption_hash exactly as it was (see the next section).
6. Update DNS to point the WHMCS domain at the new server, and wait until the change has propagated before you continue.
7. Reissue the licence. If you bought it from WHMCS, log in to the WHMCS Member Area, go to Services > My Licenses, select the licence and click Reissue. If you bought it from your hosting provider, ask them to reissue it. If you are moving to a new hosting provider, you need a new licence key.
8. Update the System URL at Configuration > System Settings > General Settings, if the address changed.
9. Set up the cron on the new server, pointing at crons/cron.php. WHMCS’s examples run it every five minutes, for example */5 * * * * php -q /path/to/whmcs/crons/cron.php; the exact command for your install is under Configuration > System Settings > Automation Settings.
10. Check payment gateway callbacks and email forwarders. Confirm that gateway webhooks and ticket email piping now reach the new server.
11. Update other locations: custom directory and storage settings, and the redirect URIs for sign-in integrations, mail providers and payment gateways that send users back to WHMCS. PayPal users may get emails about IPN failures until this is done.
12. Delete the old WHMCS files, once the new server has run cleanly. Our advice: keep the database dump and configuration.php from the old server in your backups for a while longer.

The encryption hash: the one value you cannot lose

configuration.php holds $cc_encryption_hash, a random 64-character string unique to your installation. WHMCS uses it to encrypt sensitive data in the database, and its documentation is blunt: if you lose the encryption hash value, the system won’t be able to decrypt your data.

So a database dump alone is not a complete backup. Copy configuration.php with it, and never generate a new hash on the new server for an existing database. The usual way this goes wrong is a fresh install on the new server, followed by importing the old database into it: the new install’s file carries a new hash, and the old data no longer decrypts.

What usually breaks after a WHMCS move, and how to fix it

Our advice: after the move, place a test order with a test gateway, open a ticket by email, and run one manual cron with php -q crons/cron.php while watching for errors. Those three cover most of what the table lists.

Can you move WHMCS without downtime?

Not entirely, but you can make it short. The time-consuming parts (installing PHP and the loader, copying files, testing the new server against a copy of the database) can all happen before the switch. The window itself is: stop the cron, take the final dump, restore it, switch DNS. With a low TTL prepared in advance, that is minutes for a small install. During the window, turn on Maintenance Mode (General tab of Configuration > System Settings > General Settings): it blocks the order form and Client Area, while the Admin Area, API and hooks keep working.

Moving servers, or moving platforms?

A server move is a natural moment to ask whether you want to stay on WHMCS. If you are staying, the steps above are all you need. If you are reconsidering, two of our earlier guides cover it without the sales pitch: a vendor-neutral checklist for migrating billing platforms and what changed with WHMCS pricing and price increases.

FluxBilling’s WHMCS migration tool connects straight to the WHMCS MySQL database (a read-only user is enough, optionally through an SSH tunnel) and writes nothing to WHMCS. It imports clients with their existing passwords, contacts, products and configurable options, services, invoices, payments, credit, tickets with replies and saved payment methods. It does not import domains, product addons, affiliates, quotes, knowledge base articles or email templates; there is no rehearsal mode, though re-running it skips records already imported. Where WHMCS wins plainly: a far larger module ecosystem, mature domain reselling, and a long track record, where FluxBilling is pre-1.0.

If you want to compare, FluxBilling plans start at €4.95 a month ($5.95 for US accounts) with a 14-day refund; see the WHMCS alternative page or the live demo.

Frequently asked questions

How do I move WHMCS to another server?

Disable the cron on the old server, back up the database and configuration.php, copy the files, restore the database on a server that meets the requirements, update the database settings and any absolute paths, switch DNS, reissue the licence, update the System URL, set up the cron, then check gateway callbacks and email forwarders.

Do I need a new WHMCS licence when I change server?

Usually not: you reissue the existing one, in the WHMCS Member Area under Services > My Licenses, or through the hosting provider that sold it. WHMCS says that if you move your installation to a new hosting provider, you need a new licence key.

What happens if I lose the cc_encryption_hash?

WHMCS can no longer decrypt the sensitive data encrypted with it. There is no recovery route other than the original value, so back up configuration.php alongside every database dump.

Which PHP version does WHMCS 9 need?

WHMCS 9.0 requires PHP 8.2 or 8.3, with ionCube Loader 13.0.2 or 14.4.0 or later respectively. WHMCS 8.13 still supports PHP 7.2 to 8.3. WHMCS 9.1, in beta on 20 October 2026, adds PHP 8.4.

How long does a WHMCS server move take?

The preparation can take a day; the cutover itself, with DNS TTL lowered in advance, is usually minutes for a small installation. Large databases take longer to dump and restore, so time a test restore first.

Sources

• WHMCS Documentation — “Move WHMCS to a New Server” (8.13), docs.whmcs.com, last modified 21 September 2026, read 20 October 2026.
• WHMCS Documentation — “System Requirements” for 8.13 and 9.0, read 20 October 2026.
• WHMCS Documentation — “The configuration.php File”, “Database Backups”, “Configure the System Cron Job”, “Maintenance Mode” and “ionCube Fatal Decoding Errors” (8.13), read 20 October 2026.
• WHMCS Documentation — version overview at docs.whmcs.com, read 20 October 2026.

WHMCS, WHMCS Cloud, ionCube, MySQL, MariaDB, PHP, Apache, NGINX, phpMyAdmin and PayPal are trademarks of their respective owners. FluxBilling is not affiliated with or endorsed by any of them. Third-party details are as published on the dates above and may have changed since.