Restore a WordPress Site from a Backup • WP STAGING

The restore command performs a complete restoration of a WordPress site from a WP Staging backup. It extracts files and imports the database in one operation, making it ideal for migrating sites or recovering from disasters.

What You’ll Get

After restoration:

Complete WordPress installation with all files restored
Database imported and configured
Site ready to use at the target location

Prerequisites

The restore command requires:

An existing WordPress installation at the target path (with a valid wp-config.php)
Database credentials (from wp-config.php or provided via flags)
Write permissions to the target directory

Tip: For setting up a fresh WordPress environment with Docker, use wpstaging add --from=backup.wpstg instead. See Create a Local Copy of WordPress Site.

Basic Restore

Restore a WordPress site to a specific directory:

wpstaging restore --path=/var/www/html backup.wpstg

Or, if you’re already in the WordPress root directory:

cd /var/www/html
wpstaging restore backup.wpstg

Restore from Remote URL

Restore directly from a remote backup file:

wpstaging restore --path=/var/www/html --from=https://example.com/backups/backup.wpstg

The CLI downloads the backup, validates it, and restores in one operation.

Restore to Dockerized Site

For sites managed by WP Staging CLI’s Docker environment, you can restore directly using the hostname:

wpstaging restore site.local backup.wpstg

Or with the --from flag:

wpstaging restore site.local --from=backup.wpstg
wpstaging restore site.local --from=https://example.com/backups/backup.wpstg

Requirements:

The site must already exist (created with wpstaging add site.local)
Database credentials are auto-detected from the site’s .env file
No need to specify --path or database flags

Restore with External Database

Override the database settings from wp-config.php to connect to a different database server:

wpstaging restore --path=/var/www/html \
  --db-host=db.example.com \
  --db-name=wordpress_db \
  --db-user=wp_user \
  --db-password=secret_password \
  backup.wpstg

Database Connection Options

Full control over database connection settings:

Flag	Description
`--db-host`	Database host (e.g., localhost, db.example.com)
`--db-name`	Database name
`--db-user`	Database username
`--db-password`	Database password
`--db-socket`	Database socket path
`--db-charset`	Database charset (e.g., utf8mb4)
`--db-collate`	Database collation
`--db-prefix`	Target WordPress table prefix

SSL/TLS Database Connection

For secure database connections:

wpstaging restore --path=/var/www/html \
  --db-host=secure-db.example.com \
  --db-ssl-ca-cert=/path/to/ca-cert.pem \
  --db-ssl-cert=/path/to/client-cert.pem \
  --db-ssl-key=/path/to/client-key.pem \
  backup.wpstg

Flag	Description
`--db-ssl-ca-cert`	Path to CA certificate file
`--db-ssl-cert`	Path to client certificate file
`--db-ssl-key`	Path to client key file
`--db-ssl-mode`	SSL mode (skip-verify/preferred)

Overwrite Options

Control what gets overwritten during restoration:

Flag	Default	Description
`--overwrite`	yes	Overwrite target directory files
`--overwrite-db`	yes	Overwrite database tables
`--overwrite-wproot`	no	Overwrite WordPress root files

Example – Keep existing database:

wpstaging restore --path=/var/www/html --overwrite-db=no backup.wpstg

Example – Also overwrite WordPress core files:

wpstaging restore --path=/var/www/html --overwrite-wproot=yes backup.wpstg

Filter What to Restore

Use the same --only-* and --skip-* flags as the extract command:

Restore only plugins and themes:

wpstaging restore --path=/var/www/html --only-plugins --only-themes backup.wpstg

Restore everything except uploads:

wpstaging restore --path=/var/www/html --skip-uploads backup.wpstg

See Extract Backup Files for the complete list of filter flags.

Resume Interrupted Restoration

If database restoration was interrupted, you can resume from the extracted SQL file:

wpstaging restore --path=/var/www/html \
  --skip-extract \
  --db-file=/path/to/extracted/database.sql \
  backup.wpstg

Flag	Description
`--skip-extract`	Skip extraction if files already exist
`--db-file`	Use a specific SQL file for database restoration

Database Performance Options

Fine-tune database import performance:

Flag	Default	Description
`--db-batch-size`	1000	Number of rows per INSERT statement
`--db-insert-single`	false	Use single-row INSERT statements
`--db-timeout`	15s	Database connection timeout
`--db-innodb-strict-mode`	off	Enable InnoDB strict mode during restore

Example – Slower but more compatible import:

wpstaging restore --path=/var/www/html \
  --db-insert-single \
  --db-batch-size=100 \
  backup.wpstg

Verify Restored Files

Verify file integrity after restoration:

wpstaging restore --path=/var/www/html --verify backup.wpstg

All Restore Flags

Flags:
  -o, --outputdir string          Directory for extracted files (default: ./wpstaging-output)
  -p, --path string               WordPress installation path (required)
      --site-url string           Target WordPress site URL (use if detection fails)
      --overwrite string          Overwrite target directory (yes/no) (default "yes")
      --overwrite-db string       Overwrite database (yes/no) (default "yes")
      --overwrite-wproot string   Overwrite WP root files (yes/no) (default "no")
      --db-prefix string          Target WordPress DB table prefix (use if detection fails)
      --db-innodb-strict-mode     Enable InnoDB strict mode (off by default during restore)
      --db-file string            Use the extracted backup SQL file to resume database restoration
      --db-batch-size int         Database insert batch size (default "1000")
      --db-insert-single          Use single-row INSERT statement per query
      --db-timeout string         Database connection timeout (default "15s")
      --verify                    Verify integrity of extracted files
      --skip-extract              Skip extraction if files already exist
      --from string               Backup file path or remote URL (http/https)

Troubleshooting

Database Connection Failed

Verify wp-config.php has correct database credentials
Check that the database server is running and accessible
Try providing credentials explicitly with --db-* flags
For remote databases, ensure firewall allows connections

Permission Denied

Ensure you have write permissions to the target directory
On Linux/macOS, you may need to run as the web server user or use sudo

Site URL Detection Failed

If the CLI cannot detect the site URL automatically, provide it manually:

wpstaging restore --path=/var/www/html --site-url=https://mysite.com backup.wpstg

Next Steps

Create a Local Copy of WordPress Site – Set up a Docker-based local environment
Extract Backup Files – For manual extraction without database import
Inspect Backup Files – View backup contents before restoration