ERPNext Backup and Restore with Frappe Bench: bench backup and bench restore Commands

To back up ERPNext, run bench --site yoursite backup --with-files from your frappe-bench folder: it saves the database, public files, private files and the site config to sites/yoursite/private/backups. To restore, run bench --site yoursite restore path/to/database.sql.gz --with-public-files path/to/files.tar --with-private-files path/to/private-files.tar, then bench --site yoursite migrate. The commands below work on ERPNext 13, 14, 15 and 16.

I restore the public demo at erp.syncbricks.com from a clean backup every night so testers always get fresh data, and I have moved client sites between servers with exactly these steps. The examples use the site erp.syncbricks.com; replace it with yours.

Quick reference

All commands run as the bench user from the frappe-bench directory.

What an ERPNext backup contains

The database alone is not a full backup. Attachments, images and generated files live on disk, and the site's encryption key lives in site_config.json. A full backup (--with-files) creates four files named with a timestamp and the site name:

With --compress, the file archives are .tgz instead of .tar.

How to back up ERPNext with bench backup

cd ~/frappe-bench
bench --site erp.syncbricks.com backup --with-files --compress
ls -lh sites/erp.syncbricks.com/private/backups/

The command prints the path and size of each file when it finishes. All options, from the Frappe backup reference:

Example: back up straight to a mounted NAS share.

bench --site erp.syncbricks.com backup --with-files --backup-path /mnt/nas/erpnext-backups

Automatic ERPNext backups

bench setup production runs bench setup backups, which adds a cron job for the bench user that runs bench --site all backup every 6 hours. Check it:

crontab -l

You should see a line ending in --site all backup >> .../logs/backup.log 2>&1 with the comment bench auto backups set for every 6 hours. If it is missing, run bench setup backups. To change the schedule or add --with-files, edit the line with crontab -e; my crontab guide explains the syntax.

ERPNext only keeps a few recent backups on disk (the "Number of Backups" setting in System Settings), and they sit on the same server they protect. Copy them somewhere else:

• S3 or S3-compatible storage: in ERPNext, search for S3 Backup Settings, add your bucket and keys, and enable the schedule. It works with AWS S3, Wasabi, Backblaze B2 or MinIO on a NAS.
• Google Drive or any rclone remote: run rclone copy on the backups folder from cron. I use the same method for Proxmox in my rclone and Google Drive guide.
• VM snapshots: if ERPNext runs on Proxmox, a nightly VM backup adds a second layer, but keep the bench backups too, because they restore onto any server.

How to restore ERPNext with bench restore

The format, from the Frappe restore reference:

bench --site [site-name] restore [OPTIONS] SQL_FILE_PATH

Restore the database and files

cd ~/frappe-bench
bench --site erp.syncbricks.com restore \
  sites/erp.syncbricks.com/private/backups/20261018_020001-erp_syncbricks_com-database.sql.gz \
  --with-public-files sites/erp.syncbricks.com/private/backups/20261018_020001-erp_syncbricks_com-files.tar \
  --with-private-files sites/erp.syncbricks.com/private/backups/20261018_020001-erp_syncbricks_com-private-files.tar
bench --site erp.syncbricks.com migrate

There is no need to gunzip the .sql.gz first; current bench versions read it directly. When it finishes you will see Site erp.syncbricks.com has been restored with files. Then clear the cache and restart:

bench --site erp.syncbricks.com clear-cache
sudo supervisorctl restart all

Restore the database only

This is what I run every night on the demo: the data resets, the files stay.

bench --site erp.syncbricks.com restore /home/frappe/demo/clean-database.sql.gz --db-root-password "$DB_ROOT_PASSWORD"

Move ERPNext to a new server

1. On the old server: bench --site erp.example.com backup --with-files, then copy the four files to the new server (scp or rsync).
2. On the new server, install the same major version of Frappe, ERPNext and any other apps the site uses (ERPNext 16 on Ubuntu 24.04).
3. Create a site with the same name: bench new-site erp.example.com, and install the same apps on it.
4. Copy encryption_key from the old site_config_backup.json into the new sites/erp.example.com/site_config.json.
5. Restore with files as above, then bench --site erp.example.com migrate and sudo supervisorctl restart all.

Moving the database to its own server instead? See ERPNext with an external MariaDB database.

Troubleshooting bench restore

Restore stops part way or fails with ERROR 1064. The SQL file is incomplete or the copy was interrupted. Compare its size with the original and check gunzip -t file.sql.gz.

Your site will be downgraded warning. The backup came from a newer version than the bench you are restoring into. Update the bench to that version first (bench update) rather than using --force, which can leave the schema broken.

ModuleNotFoundError or missing DocTypes after restore. The old site had apps (HRMS, custom apps) that the new bench does not. Run bench get-app and install-app for them, then migrate.

Encryption key is invalid or Decryption failed after restore. The new site has a different encryption_key. Copy the old one from site_config_backup.json into site_config.json.

Access denied for user 'root'@'localhost'. bench needs the MariaDB root password; pass --db-root-username and --db-root-password, or set a root password as shown in the installation guide.

Restore is very slow on a large database. Restore during a quiet window, and check free disk space with df -h: you need room for the unpacked SQL plus the database itself.

Related guides

• ERPNext installation methods compared
• ERPNext Docker installation: back up a Docker site with docker compose exec backend bench --site frontend backup --with-files.