A cpmove file is the archive cPanel and WHM use to transfer or restore a hosting account, including its home directory, MySQL databases, email accounts, and DNS zone data. This guide covers what a cpmove file is, how to create one, how to restore from one using WHM or the command line, and how to fix the most common errors that come up during the process.
What is a CPMOVE file?
A cpmove file is a compressed archive (usually .tar.gz) generated by cPanel that contains a complete snapshot of a hosting account. It’s the format used internally by WHM’s account transfer, backup, and restore tools.
A typical cpmove archive includes:
- The account’s home directory (website files, public_html, etc.)
- MySQL/MariaDB database dumps
- Email accounts, forwarders, and filters
- DNS zone file records
- cPanel account configuration (package, resource limits, addon/sub/parked domains)
- SSL certificates, if installed
Because it bundles everything needed to recreate an account, a CPMove file is what most admins use when migrating accounts between servers or restoring a full account after data loss.
cpmove file vs. a regular tarball backup
A standard cPanel backup tarball (created via the “Backup” feature in cPanel) and a cpmove file contain similar data, but cpmove files follow a strict naming and structure convention that WHM’s restore tool expects. A renamed tarball won’t always restore cleanly unless it matches the required naming patterns below.
Naming and Location Requirements
WHM’s restore tool only recognizes archive files that match specific naming patterns and live in specific directories. If your file doesn’t meet both conditions, the restore will fail even if the file itself is valid.
Accepted filename formats:
cpmove-{USER}cpmove-{USER}.tarcpmove-{USER}.tar.gz{USER}.tar{USER}.tar.gzbackup-{MM.DD.YYYY}_{HH-MM-SS}_{USER}.tarbackup-{MM.DD.YYYY}_{HH-MM-SS}_{USER}.tar.gz
Accepted directories:
/home/home2/home3/root/usr/usr/home/web
If your file is sitting anywhere else (like /tmp or a mounted backup drive), move or symlink it into one of these directories before attempting the restore.
How to Create a cpmove File
Before you can restore an account, you usually need to generate the cpmove file in the first place, either on the same server (for a backup) or on the source server (for a migration).
Using WHM (GUI method):
- Log in to WHM as root.
- Go to Backup → Backup Configuration, or use Transfers → Copy multiple accounts if you’re moving to a different server.
- Select the account(s) you want to archive and start the backup/transfer job.
- WHM will generate a cpmove-{USER}.tar.gz file and place it in /home by default.
Using the command line (pkgacct):
/scripts/pkgacct username
This packages the specified account into a cpmove file and saves it to /home by default. Useful options include:
- –skiphomedir – exclude the home directory to speed up packaging for large accounts
- –skipbwdata – exclude bandwidth statistics
- –newuser – package the account under a different username
How to Restore an Account from a cpmove File
- Log in to WHM as the root user.
- Search for “Transfers” in the WHM search bar.
- Click “Transfer or Restore a cPanel Account.”
- Select “Restore a local cpmove file.”
- Choose the file from the dropdown, or browse to its location if it isn’t auto-detected.
- Check “Overwrite if the cPanel user already exists” if you’re restoring over an existing account with the same username. This step is optional and only needed in that scenario.
- Choose an A record option:
- Replace all instances of the source server’s IP with the destination server’s IP – the default, recommended setting for most restores.
- Use cPanel-provided A records – substitutes standard cPanel-generated A records into the zone file instead.
- Click Restore. WHM opens the Account Restore screen and starts the job. You can monitor progress live from this screen.
Common cpmove Restore Errors and How to Fix Them
“Account already exists” or restore halts on a duplicate username
Re-run with –force, or remove/rename the existing account first via WHM’s account termination tool.
“Invalid archive” or “incompatible package” error
Usually means the file was packaged on a much newer or older cPanel version than the destination server, or the archive is corrupted/incomplete. Re-download or re-generate the cpmove file and verify its integrity with tar -tzf filename.tar.gz before retrying — this lists the archive contents without extracting, so a corrupted file will throw an error immediately.
Restore fails with a “file not found” error even though the file exists
Almost always, a naming or location issue. Double-check the filename matches one of the accepted patterns and that the file sits in one of the directories listed above.
Restore completes, but the website doesn’t load
Check that DNS/A records actually point to the new server and that the zone file was updated correctly during restore. This is the most common post-restore issue, especially with cross-server migrations.
Email or databases are missing after the restore
If –skiphomedir, –skipbwdata, or similar flags were used during either packaging or restore, some components may have been deliberately excluded. Re-run a full restore without skip flags if you need everything.
Restore is extremely slow or times out in the GUI
Large accounts (large home directories or huge mail stores) can exceed the WHM interface’s patience. Use the restorepkg command line method instead, it runs as a background process and isn’t subject to browser/session timeouts.
Frequently Asked Questions
- What is a cpmove file used for?
A cpmove file is used to transfer or restore a complete cPanel hosting account, including files, databases, email, and DNS settings, either on the same server or when migrating to a new one. - How do I restore a cPanel account from a backup?
Use WHM’s “Transfer or Restore a cPanel Account” tool and select “Restore a local cpmove file,” or run the restorepkg script from the command line as root. - What does restorepkg do?
restorepkg is the command-line script that performs the actual account restoration from a cpmove file, rebuilding the account’s files, databases, email, and configuration on the server. - Where should cpmove files be stored on the server?
WHM only recognizes cpmove files in /home, /home2, /home3, /root, /usr, /usr/home, or /web. Files elsewhere need to be moved into one of these directories first. - Can I restore a cpmove file to a server with a different cPanel version?
Generally, yes, between minor versions, but restoring across major version gaps can trigger “incompatible package” errors. Where possible, restore to a server running the same or a newer cPanel version than the one that created the file.
Need Help?
If you run into an error not covered here, or you’d rather have it handled for you, contact the bodHOST support team available 24×7 for account restore and migration assistance
Learn the more knowledge base about how to use WHM to remove the cPanel Accounts