How to back up and restore a Joomla site

What a complete Joomla backup includes

Joomla is free, open-source software under the GNU GPL. This guide covers Joomla 5 and 6 (5.4.9 and 6.1.4 were released on 29 September 2026). The site lives in /var/www/example.com and PHP runs as www-data, as on Debian and Ubuntu.

Read the database settings from configuration.php

configuration.php defines a JConfig class with one property per setting. Print the database lines:

grep -E 'public \$(dbtype|host|user|db|dbprefix) ' /var/www/example.com/configuration.php

• $dbtype is mysqli or mysql for MySQL and MariaDB, or pgsql for PostgreSQL.
• $host can carry a port or socket after a colon, such as 127.0.0.1:3307; mysqldump needs it as a separate port= or socket= line in its option file.
• $dbprefix starts the name of every Joomla table, for example abc12_. The restored tables must keep it.

Joomla's CLI shows the same group, password included: sudo -u www-data php /var/www/example.com/cli/joomla.php config:get --group db. Run the CLI as the web server user so any files it writes stay usable by PHP.

Dump a MySQL or MariaDB database

install -d -m 700 /var/backups/joomla

Put the user and password from configuration.php in an option file, so the password stays out of ps and your shell history:

[client]
user=joomla
password="your-password-here"
host=localhost

chmod 600 /etc/mysql/joomla-backup.cnf

mysqldump --defaults-extra-file=/etc/mysql/joomla-backup.cnf --single-transaction --no-tablespaces joomla | gzip > /var/backups/joomla/example.com-db-$(date +%F).sql.gz

• --single-transaction reads InnoDB tables from one consistent snapshot without locking them, so the site stays up. Joomla's core tables are InnoDB, apart from two MEMORY tables Smart Search uses while indexing.
• --no-tablespaces avoids the global PROCESS privilege, which a site's database user rarely has.
• The dump covers the whole database, including tables with other prefixes. On MariaDB 11 the same program is called mariadb-dump.

A complete dump ends with a -- Dump completed on line. Check it, then list the engines in use: a third-party extension's MyISAM tables can change mid-dump, because --single-transaction only covers transactional tables:

gunzip -c /var/backups/joomla/example.com-db-2026-10-04.sql.gz | tail -n 1

mysql --defaults-extra-file=/etc/mysql/joomla-backup.cnf -e "SELECT ENGINE, COUNT(*) FROM information_schema.TABLES WHERE TABLE_SCHEMA = 'joomla' GROUP BY ENGINE"

On PostgreSQL, store the password in /root/.pgpass and write a custom-format dump, which pg_restore --list can check without restoring it. The pg_dump guide covers both:

pg_dump -h localhost -U joomla -Fc -f /var/backups/joomla/example.com-db-$(date +%F).dump joomla

What about php cli/joomla.php database:export?

Joomla's CLI includes database:export and database:import, which come from the Joomla Framework's database package. Their source shows why they are no substitute for a dump:

• They write one XML file per table in Joomla's own format, which only database:import reads. You cannot load it with mysql or psql.
• Each table is read on its own, outside any transaction, so on a busy site the tables come from different moments. Each table's XML is built in memory first.
• Only tables that start with $dbprefix are exported.
• The options are --folder, --table and --zip. Guides that add --all get The "--all" option does not exist.
• database:import drops each table before loading its file.

Joomla core has no other backup feature. Use mysqldump or pg_dump for the database and tar for the files.

Archive the site files

Dump the database first, then the files, so the database never points at a file the archive lacks. Leave configuration.php out of this archive; it gets its own below.

tar -czf /var/backups/joomla/example.com-files-$(date +%F).tar.gz --exclude='example.com/configuration.php' --exclude='example.com/cache/*' --exclude='example.com/administrator/cache/*' --exclude='example.com/tmp/*' --exclude='example.com/administrator/logs/*' -C /var/www example.com

• -C /var/www example.com stores paths as example.com/..., so the archive extracts anywhere.
• A /* pattern drops a folder's contents but keeps the folder itself, which Joomla needs.
• Exclude patterns match the stored names and must come before the directory.

tar run as root records owners and permissions. The tar guide explains excludes and how to test an archive.

Keep configuration.php and $secret

$secret is a random string the installer writes into configuration.php. Joomla encrypts every user's multi-factor authentication settings with it, authenticator keys and backup codes included, and checks Web Services API tokens against an HMAC made with it. Under a different $secret, users with multi-factor authentication cannot finish signing in and every API token is rejected. Passwords do not depend on it.

tar -czf /var/backups/joomla/example.com-config-$(date +%F).tar.gz -C /var/www example.com/configuration.php

Offline mode during a backup

A dump with --single-transaction does not need the site offline. Take it offline for the final backup before a move, so nothing changes between the last dump and the switch:

sudo -u www-data php /var/www/example.com/cli/joomla.php site:down

site:down sets $offline = true in configuration.php and site:up sets it back; visitors see the offline page in between. Because the flag lives in configuration.php, not the database, a copy archived while offline restores an offline site. Run the CLI as the user that owns configuration.php, since it rewrites the file.

Restore on a new server

Joomla 6 needs PHP 8.3 or later and MySQL 8.0.13, MariaDB 10.4 or PostgreSQL 12 at least; Joomla 5's CLI accepts PHP 8.1. Create an empty database and user:

CREATE DATABASE joomla CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'joomla'@'localhost' IDENTIFIED BY 'your-password-here';
GRANT ALL PRIVILEGES ON joomla.* TO 'joomla'@'localhost';

tar -xzf /var/backups/joomla/example.com-files-2026-10-04.tar.gz -C /var/www

tar -xzf /var/backups/joomla/example.com-config-2026-10-04.tar.gz -C /var/www

Edit configuration.php for this server. These lines usually change. Keep $secret and $dbprefix exactly as they were:

public $host = 'localhost';
public $user = 'joomla';
public $password = 'your-password-here';
public $db = 'joomla';
public $live_site = '';
public $tmp_path = '/var/www/example.com/tmp';
public $log_path = '/var/www/example.com/administrator/logs';

• $tmp_path and $log_path are absolute paths written at install. Point them at this server's folders.
• $live_site is normally empty. When set, Joomla builds every URL from it, so an old value sends links and stylesheets to the old address.
• $force_ssl is 0 for none, 1 for the administrator, 2 for both. Use 0 until the new server has a certificate.
• If $session_handler or $cache_handler is redis or memcached, install it or switch to database and file. Fix $cookie_domain if it names the old domain.

Then load the dump and give the files to the PHP user:

gunzip -c /var/backups/joomla/example.com-db-2026-10-04.sql.gz | mysql --defaults-extra-file=/etc/mysql/joomla-backup.cnf joomla

chown -R www-data:www-data /var/www/example.com

On PostgreSQL, create the role and database, then run pg_restore --no-owner -h localhost -U joomla -d joomla with the .dump file; restoring a PostgreSQL dump covers the details. Finally clear the cache, and run site:up if the site came back offline:

sudo -u www-data php /var/www/example.com/cli/joomla.php cache:clean

Verify the restore

On Joomla 5.2 and later, compare the database schema with what the installed code expects:

sudo -u www-data php /var/www/example.com/cli/joomla.php maintenance:database

It lists each extension and ends with All database table structures are up to date. or, when something differs, There are tables not up to date!. Since the files and database come from the same night, there should be nothing to fix. Then count articles (with your table prefix) and compare with the live site, and fetch the home page, expecting 200:

mysql --defaults-extra-file=/etc/mysql/joomla-backup.cnf joomla -e "SELECT COUNT(*) FROM abc12_content"

curl -sS -o /dev/null -w '%{http_code}\n' https://example.com/

In the administrator, System > Information > System Information > Folder Permissions shows whether the temp and log folders are writable, and System > Information > Warnings flags a wrong $tmp_path. Sign in as a user with multi-factor authentication and open a page with images. Testing restores explains how to make this routine.

Automate it with cron

This script writes each file under a temporary name, checks the dump, and only then gives it its real name. tar exits with 1 when a file changed while it was read, so 1 counts as success.

#!/bin/bash
set -euo pipefail

SITE_DIR="/var/www"
SITE="example.com"
DB_NAME="joomla"
BACKUP_DIR="/var/backups/joomla"
KEEP_DAYS=14
STAMP="$(date +%Y-%m-%d_%H%M)"
DB="$BACKUP_DIR/$SITE-db-$STAMP.sql.gz"
FILES="$BACKUP_DIR/$SITE-files-$STAMP.tar.gz"

mkdir -p "$BACKUP_DIR"
trap 'rm -f "$DB.partial" "$FILES.partial"' EXIT

mysqldump --defaults-extra-file=/etc/mysql/joomla-backup.cnf \
  --single-transaction --no-tablespaces "$DB_NAME" | gzip > "$DB.partial"
gunzip -c "$DB.partial" | tail -n 1 | grep -q "Dump completed"
mv "$DB.partial" "$DB"

tar -czf "$FILES.partial" \
  --exclude="$SITE/configuration.php" \
  --exclude="$SITE/cache/*" --exclude="$SITE/administrator/cache/*" \
  --exclude="$SITE/tmp/*" --exclude="$SITE/administrator/logs/*" \
  -C "$SITE_DIR" "$SITE" || [ $? -eq 1 ]
mv "$FILES.partial" "$FILES"

find "$BACKUP_DIR" -type f \( -name "$SITE-db-*" -o -name "$SITE-files-*" \) -mtime +"$KEEP_DAYS" -delete

chmod 755 /usr/local/bin/joomla-backup.sh

PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

25 3 * * * root flock -n /run/lock/joomla-backup.lock /usr/local/bin/joomla-backup.sh >> /var/log/joomla-backup.log 2>&1

-mtime +14 keeps about two weeks of nightly backups and leaves the configuration archives alone, and flock -n stops two runs overlapping. Copy the backups off the server each night, for example with rclone to Backblaze B2; the cron guide covers logging and alerts.

Common errors

Frequently asked questions

Does Joomla have a built-in backup?

No. Joomla core has no backup feature. The CLI's database:export writes one XML file per table in Joomla's own format, table by table without a transaction, and covers no files. Use mysqldump or pg_dump and tar.

Which Joomla folders do I need to back up?

The whole site directory, because extensions install into the core folders, minus the contents of cache, administrator/cache and tmp. Back up configuration.php separately and the database with mysqldump or pg_dump.

What happens if I lose configuration.php?

Rebuild it from configuration.php-dist in the Joomla package with the old database name, user and $dbprefix. A new $secret makes multi-factor authentication settings and API tokens unusable, so users must set those up again.

Do I need to take Joomla offline to back it up?

Not with mysqldump --single-transaction, which reads InnoDB tables from one snapshot while the site runs. Use php cli/joomla.php site:down for the final backup before moving servers, and site:up afterwards.