cPanel & WHM CLI: Back Up, Move, and Restore an Account
A practical cPanel and WHM command-line guide for creating cpmove backups, moving accounts between servers, restoring them safely, and checking what went wrong.
You need to move a cPanel account, restore a broken one, or make a backup before touching something scary. The CLI is faster than clicking through WHM. It is also very good at doing exactly what you told it to do.
This guide covers the commands I use most: pkgacct, restorepkg, scp, and whmapi1.
Two paths to keep in your head: the scripts live in /usr/local/cpanel/scripts, and account files usually live in /home/USERNAME.
The short version
Create a full account archive:
/usr/local/cpanel/scripts/pkgacct USERNAME /homeThis creates /home/cpmove-USERNAME.tar.gz.
Copy it to another server (you will need SSH access):
scp /home/cpmove-USERNAME.tar.gz root@NEW_SERVER:/home/Restore it there:
/usr/local/cpanel/scripts/restorepkg /home/cpmove-USERNAME.tar.gzRun these as root. They change server-level cPanel config, not just files in someone’s home directory.
Check free disk space first
Don't trust --force blindly
What is a cpmove archive?
pkgacct creates a portable cpmove archive. It contains the account’s files, databases, mail, DNS data, SSL data, cron jobs, and cPanel settings.
You normally do not need to unpack it. cPanel knows the format already. That is one less tarball archaeology project.
Back up one cPanel account
That’s the pkgacct line from the short version. Keep the explicit /home at the end: it makes the archive easy to find.
To inspect it without extracting it:
tar -tzf /home/cpmove-USERNAME.tar.gz | lessTo compare the file after copying it, make a checksum on both servers:
sha256sum /home/cpmove-USERNAME.tar.gzSTOP. Mystery archive.1 character out of 64 is different. That is enough.
The two hashes should match. If they do not, stop there. Do not restore a mystery archive.
Restore a cPanel backup
restorepkg accepts either a full path to an archive, like in the short version, or a username. The full path is clearer. Restoring by username works when the archive is in one of cPanel’s search paths, such as /home:
/usr/local/cpanel/scripts/restorepkg USERNAMERestoring an existing account
Be careful here. If the account already exists, --force behaves much like --skipaccount: it restores what it can while leaving existing data on the server.
/usr/local/cpanel/scripts/restorepkg --force /home/cpmove-USERNAME.tar.gzThat can leave a confusing mix of old and restored data. If you need a clean replacement, take a fresh backup, plan the downtime, and test the restore on a staging server first.
Restore under a different username
Use --newuser when the target username must change:
/usr/local/cpanel/scripts/restorepkg --newuser NEWUSER /home/cpmove-OLDUSER.tar.gzThe new name must not exist. It must be 16 characters or fewer, and its first eight characters must be unique on the server. Database users do not all get renamed automatically, so check the application configuration after the restore.
Where cPanel keeps account files
Most accounts live under /home, but a server can use other home partitions too. Do not assume every account lives in the same cupboard.
| What | Typical path |
|---|---|
| Account home | /home/USERNAME/ |
| Website root | /home/USERNAME/public_html/ |
/home/USERNAME/mail/ | |
| Account config | /var/cpanel/users/USERNAME |
| DNS zones | /var/named/ |
| Apache logs | /usr/local/apache/logs/ |
The cpuser file at /var/cpanel/users/USERNAME is the main account configuration file. Read it before editing it. Better yet, use WHM or a documented script where possible.
Useful WHM and cPanel commands
List accounts:
whmapi1 listacctsShow one account:
whmapi1 accountsummary user=USERNAMEWant JSON instead of YAML?
whmapi1 --output=jsonpretty accountsummary user=USERNAMEOn CloudLinux, use the full command path:
/usr/local/cpanel/bin/whmapi1 accountsummary user=USERNAMEOther useful scripts:
| Job | Command |
|---|---|
| Create an account archive | /usr/local/cpanel/scripts/pkgacct USERNAME /home |
| Restore an archive | /usr/local/cpanel/scripts/restorepkg ARCHIVE |
| Remove an account | /usr/local/cpanel/scripts/removeacct USERNAME |
| Rebuild Apache config | /usr/local/cpanel/scripts/rebuildhttpdconf |
| Restart Apache | /usr/local/cpanel/scripts/restartsrv_httpd |
| Update domain mappings | /usr/local/cpanel/scripts/updateuserdomains |
Use the full script path. cPanel recommends it, even if you are already in /usr/local/cpanel/scripts.
Remove an account
This deletes the account’s data. Make a backup first.
/usr/local/cpanel/scripts/removeacct USERNAMEThe script asks for confirmation. --force skips that prompt. It does not make the command less destructive.
A quick recovery checklist
The command finishing is not the same thing as the migration finishing.
- Create a
cpmovearchive withpkgacct. - Copy it to the destination.
- Compare the checksum on both servers.
- Restore it with
restorepkg. - Check the website and database connection. A crashed MySQL table looks like a broken site with no useful error.
- Check mail (SPF, DKIM and DMARC), DNS, SSL, and cron jobs.
- Keep the archive until you are happy with the result.
FAQ
Where does pkgacct save the backup?
If you pass /home as the final argument, it saves the archive there. Without a directory, cPanel uses the home directory with the most free space.
Can I restore a cpmove archive on another cPanel server?
Yes. That is what pkgacct archives are for. Make sure the target server has enough free disk space and a compatible cPanel setup.
Does a cpmove archive transfer two-factor authentication?
No. cPanel does not transfer an account’s 2FA configuration. The user must set it up again on the new server.
Should I extract the archive before restoring it?
Usually, no. Give the archive directly to restorepkg. Extract it only when you need to inspect a file or recover a small piece of data.
Sources
Comments
Comments live in GitHub Discussions (via giscus), so you need a GitHub account to join in.