When a website goes down due to a misconfiguration, accidental deletion, or a server failure, knowing how to perform a WHM restore cPanel account from backup can be the difference between a 10-minute recovery and a full day of downtime. This guide covers every method — from the WHM GUI to raw SSH commands — so you can restore cPanel accounts confidently, even under pressure. Whether you're dealing with a cpmove file, a full compressed backup, or a partial database-only restore, we have you covered.
Understanding cPanel Backup Types: Full, Incremental, and cpmove Files
Before running a single command, it pays to know exactly what kind of backup you're working with. cPanel and WHM generate several distinct backup formats, and choosing the wrong restore method for a given format will either fail outright or leave your account in a broken state.
Full cPanel Backups
A full cPanel backup is a compressed archive (typically .tar.gz) of an entire account — files, databases, email, DNS zone, cron jobs, SSL certificates, and account metadata. These are generated by WHM » Backup Configuration when "Full Backup" is selected, or manually via the cPanel backup wizard. Full backups are the safest restore source because they contain everything needed to recreate the account from scratch.
File naming convention: backup-MM.DD.YYYY_HH-MM-SS_username.tar.gz
cpmove Files
A cpmove file is structurally identical to a full backup but uses a different naming format: cpmove-username.tar.gz. cpmove files are produced when you use WHM » Transfer or Restore a cPanel Account or the /scripts/pkgacct command to package an account on a source server before migrating it. The restore process for cpmove files is identical to full backups — WHM and restorepkg treat them the same way.
Incremental Backups
Incremental backups (available via JetBackup and some third-party solutions) store only the files and databases that changed since the last full backup. These cannot be restored with restorepkg directly — they require their own restore interface (e.g., JetBackup's WHM plugin). If you're using cPanel's built-in backup system without a third-party plugin, you will not encounter incremental backups.
Partial Backups (Home Directory, Database, Email)
cPanel users can also generate partial backups from within their cPanel account (not WHM). These produce separate archives for the home directory, individual MySQL databases, email forwarders, and email filters. Restoring these partial backups is covered in the "Restore Just a Database or Specific Files" section below.
Where Backups Are Stored by Default
/backup/— Default WHM backup destination (configurable)/home/and subdirectories — Common manual upload/staging location/home2/,/home3/,/root/,/usr/,/web/— All searched byrestorepkg
Important: /scripts/restorepkg searches a fixed list of directories. If your backup is outside that list (e.g., /tmp/ or a custom mount), you must either move it into /home/ or pass the full path explicitly.
💡 None of these worked? Skip the guesswork.
Get Expert Help →Restoring a cPanel Account via WHM GUI: Step-by-Step
The WHM graphical interface is the easiest path for single-account restores and is safe for administrators who prefer not to use the command line.
Prerequisites: Root or reseller-level WHM access, the backup file accessible on the server or uploadable via SFTP.
Connect via SFTP (FileZilla, WinSCP, or scp from another server) and upload the .tar.gz backup to /home/. This is the most reliable location for WHM to detect it automatically.
scp backup-01.15.2025_03-00-01_exampleuser.tar.gz root@your.server.ip:/home/Navigate to https://your-server-ip:2087 and log in as root (or a reseller with the restore permission enabled).
In the WHM search bar, type "Restore" and select Backup » Restore a Full Backup/cpmove File.
WHM presents two options:
- Username — WHM auto-detects the backup file in the standard directories. Select the username from the dropdown. This only works if the backup file is already in one of the default search paths.
- File — Browse to the exact file path. Use this when the backup is in a non-standard location.
If the account already exists on the server (e.g., you're restoring over a broken account), check the "Overwrite an Existing User" checkbox. Without this, WHM will abort if it finds an account with the same username.
WHM streams the restore log in real time. Watch for lines like:
Extracting backup...
Restoring MySQL databases...
Restoring DNS zone...
Restore complete.If you see ERROR lines, note them — common errors are covered later in this guide.
After completion, navigate to WHM » Account Information » List Accounts and confirm the account appears with the correct domain, username, and disk usage.
tar -xzf /home/cpmove-exampleuser.tar.gz --wildcards '*/mysql/*.sql.gz' -C /tmp/find /tmp -name "*.sql.gz" | grep exampleusergunzip /tmp/homedir/mysql/exampleuser_dbname.sql.gz
mysql -u root -p exampleuser_dbname < /tmp/homedir/mysql/exampleuser_dbname.sqlRestoring Specific Files from a cPanel Backup
tar -tzf /home/cpmove-exampleuser.tar.gz | grep "public_html/wp-config.php"tar -xzf /home/cpmove-exampleuser.tar.gz homedir/public_html/wp-config.php -C /tmp/cp /tmp/homedir/public_html/wp-config.php /home/exampleuser/public_html/wp-config.php
chown exampleuser:exampleuser /home/exampleuser/public_html/wp-config.phpRestoring Email from a cPanel Partial Backup
If a user downloaded a partial email backup (mail-username.tar.gz) via their cPanel, you can restore it through cPanel » Email Accounts » Restore, or extract the Maildir structure manually to /home/username/mail/.
Common WHM Restore Errors and How to Fix Them
Error: "Account already exists" / Restore Aborted
Cause: The username or domain is already in use on the server.
Fix: Use the --force flag with restorepkg, or check the "Overwrite an Existing User" box in WHM GUI. If the domain is registered to a different account, you must terminate that account first via WHM » Account Functions » Terminate Accounts.
Error: "Could not restore MySQL databases" / MySQL Error 1044 or 1045
Cause: MySQL grants for the restored user's databases are missing or the MySQL root password doesn't match.
Fix:
# Re-run the MySQL restore portion only
/scripts/restoremysql /home/cpmove-exampleuser.tar.gz
# Or re-sync MySQL grants
/scripts/mysqlperm --allError: "Archive is corrupt" or Extraction Fails
Cause: The backup file was transferred incompletely (common with FTP in ASCII mode) or was corrupted at source.
Fix: Verify the archive integrity before restoring:
tar -tzf /home/cpmove-exampleuser.tar.gz > /dev/null && echo "Archive OK" || echo "CORRUPT"Re-download the backup via SFTP (binary mode) or rsync if the test fails.
Error: "restorepkg: command not found"
Cause: Running from a non-root shell or wrong path.
Fix: Always run as root and use the full path:
sudo /scripts/restorepkg exampleuserError: DNS Zone Not Restored / Website Shows Wrong Content
Cause: DNS zone was skipped or the local nameserver wasn't updated after restore.
Fix: Run the DNS rebuild:
/scripts/rebuilddnszone exampleuser
/scripts/restartsrv_namedError: "Could not restore cron" or Missing Cron Jobs
Cause: Backup was made before cron jobs were scheduled, or crontab extraction failed.
Fix: Manually extract the crontab from the backup:
tar -xzf /home/cpmove-exampleuser.tar.gz crontabs/exampleuser -C /tmp/
crontab -u exampleuser /tmp/crontabs/exampleuserPost-Restore Verification Checklist: DNS, Email, MySQL, File Permissions
A successful restorepkg run doesn't always mean everything is working. Go through this checklist before declaring the restore complete.
1. Verify the Account in WHM
# Check account exists
/scripts/whoowns yourdomain.com
# Check disk usage
du -sh /home/exampleuser/2. Check DNS Resolution
# Confirm the zone is loaded in BIND
/scripts/dnszone yourdomain.com
# Force a DNS reload
/scripts/restartsrv_named
# Test from external resolver
dig yourdomain.com @8.8.8.83. Verify MySQL Databases and Users
# List databases for user
mysql -u root -e "SHOW DATABASES LIKE 'exampleuser%';"
# Verify user grants
mysql -u root -e "SHOW GRANTS FOR 'exampleuser_dbuser'@'localhost';"4. Check Email Functionality
Log in to Webmail at https://yourdomain.com/webmail. If login fails, check whether Dovecot recognises the account:
/scripts/restartsrv_dovecot
/usr/local/cpanel/bin/checkpasswd exampleuser5. Fix File Ownership and Permissions
After a force-restore, file ownership can sometimes end up as root instead of the cPanel user:
# Fix ownership for the entire account
chown -R exampleuser:exampleuser /home/exampleuser/
# Fix public_html permissions
find /home/exampleuser/public_html -type d -exec chmod 755 {} \;
find /home/exampleuser/public_html -type f -exec chmod 644 {} \;
# Run cPanel's built-in fix script
/scripts/fixetchosts
/scripts/fixmailperm exampleuser6. Test the Website in a Browser
Load the domain over both HTTP and HTTPS. If SSL shows as invalid post-restore, re-issue the certificate:
/scripts/install_lets_encrypt_autossl_provider
/usr/local/cpanel/bin/autossl_check --user=exampleuser7. Review the Restore Log
cat /var/cpanel/logs/restorepkg_logLook for any ERROR or WARN entries that may indicate partial failures even when the overall restore appeared to succeed.
FAQs
If you need expert assistance with restores, server migrations, or disaster recovery planning, our team provides managed cPanel server support with fast response times and full-account restore SLAs.
Conclusion
Restoring a cPanel account from a WHM backup is a multi-step process, but with the right commands and a methodical checklist, it becomes a reliable, repeatable procedure. Use the WHM GUI for single-account restores when time permits, and rely on /scripts/restorepkg over SSH when you need speed, batch processing, or scripted disaster recovery. Always verify DNS, MySQL, email, and file permissions after every restore — a technically successful extraction doesn't guarantee a functionally healthy account. Building and testing your restore procedure before a real incident is the hallmark of professional server management.
