How to back up Neo4j

Edition and version decide the method

neo4j-admin --version

cypher-shell -u neo4j "CALL dbms.components() YIELD name, versions, edition;"

The second command shows the edition; cypher-shell reads the password from NEO4J_PASSWORD or -p. Since 2025.01 Neo4j uses calendar versions: in October 2026 the current release is 2026.09, and 5.26 is the long-term support release. The commands below are the same in both.

What to back up

• neo4j, the default database (or whatever yours is called): the graph.
• system: users, roles, privileges and the state of each database. A dump of neo4j holds no users.
• neo4j.conf and neo4j-admin.conf: in /etc/neo4j for Debian and RPM packages, <NEO4J_HOME>/conf for the tarball.
• Plugins (/var/lib/neo4j/plugins), TLS certificates (/var/lib/neo4j/certificates) and any license files for Enterprise add-ons.

Packages keep data in /var/lib/neo4j/data: stores under databases/, transaction logs under transactions/. sudo du -sh /var/lib/neo4j/data/databases/neo4j gives a rough upper bound for the dump, which is compressed.

Dump with Neo4j stopped

sudo systemctl stop neo4j

sudo install -d -m 700 -o neo4j -g neo4j /var/backups/neo4j /var/backups/neo4j/2026-10-04

sudo -u neo4j neo4j-admin database dump neo4j --to-path=/var/backups/neo4j/2026-10-04

sudo -u neo4j neo4j-admin database dump system --to-path=/var/backups/neo4j/2026-10-04

sudo systemctl start neo4j

• --to-path is a directory that must already exist; the file inside is always <database>.dump. Keep that name, because load finds the archive by it: date the directory, not the file.
• Neo4j says to run neo4j-admin as the neo4j user, so the files keep the right owner. The backup directory must not be world-readable, hence mode 700.
• --overwrite-destination=true replaces an existing dump; without it the command refuses.
• --to-stdout writes the dump to standard output for piping. --to-path also accepts s3://, gs:// and azb:// locations.
• From 2026.09, --split-archive-part-size=100G splits a large dump into parts (minimum 1 GiB); keep the parts together.

Run it every night

#!/bin/bash
set -euo pipefail
DEST="/var/backups/neo4j/$(date +%F-%H%M)"
install -d -m 700 -o neo4j -g neo4j "$DEST"

systemctl stop neo4j
trap 'systemctl start neo4j' EXIT
for db in neo4j system; do
  sudo -u neo4j neo4j-admin database dump "$db" --to-path="$DEST"
done
systemctl start neo4j
trap - EXIT

cp -a /etc/neo4j "$DEST/conf"
find /var/backups/neo4j -mindepth 1 -maxdepth 1 -type d -mtime +1 -exec rm -rf {} +
echo "$(date -Is) dumped to $DEST"

sudo chmod 700 /usr/local/bin/neo4j-backup.sh

15 3 * * * root /usr/local/bin/neo4j-backup.sh >> /var/log/neo4j-backup.log 2>&1

The trap starts Neo4j again even if a dump fails. Neo4j is down from the stop to the start, so run the script once by hand with time and pick an hour that can absorb it. The find line keeps about two days of dumps. Copy them off the server (3-2-1 rule); cron schedules covers alerts.

Check a dump

sudo -u neo4j neo4j-admin database load --info --from-path=/var/backups/neo4j/2026-10-04 neo4j

--info loads nothing; it prints the database name, archive format, file count and bytes, which shows the file is a readable dump. The consistency checker goes further and checks the graph itself:

sudo -u neo4j neo4j-admin database check --from-path=/var/backups/neo4j/2026-10-04 --max-off-heap-memory=2G --report-path=/var/backups/neo4j/2026-10-04 neo4j

• It unpacks the dump into a staging directory (--temp-path, by default the --from-path directory), so it needs about the store's size free there.
• By default it may use 90% of free memory; --max-off-heap-memory caps that if Neo4j is running on the same server.
• A clean result exits 0 and writes nothing. Errors exit non-zero and write inconsistencies-<date>.report to --report-path.

Restore a dump

sudo systemctl stop neo4j

sudo -u neo4j neo4j-admin database load --from-path=/var/backups/neo4j/2026-10-04 --overwrite-destination=true neo4j

sudo -u neo4j neo4j-admin database load --from-path=/var/backups/neo4j/2026-10-04 --overwrite-destination=true system

sudo systemctl start neo4j

--overwrite-destination=true replaces the existing database. Loading system prints a warning that the dump may hold metadata from the DBMS it was taken from; on a standalone server that is the point, since it brings the old users and passwords back. Skip it to keep the current users. If you ran load as root, the files belong to root and Neo4j can't open them: sudo chown -R neo4j:neo4j /var/lib/neo4j/data. Then compare counts with figures taken before:

cypher-shell -u neo4j "MATCH (n) RETURN count(n) AS nodes;"

Restore on a new server

Install the same Neo4j version or newer, same edition, and stop it. Copy the dated directory across (copying files between servers), restore plugins and certificates, and carry over the settings you changed in neo4j.conf rather than replacing the new file when versions differ. Then load both dumps as above. Do a restore like this on a scratch server every month and time it (testing restores).

Neo4j in Docker

The official image keeps the databases under /data. Stop the container, run the dump from the neo4j/neo4j-admin image against the same volume, then start it. Use your server's exact version as the tag, with -enterprise added for Enterprise:

docker stop neo4j

docker run --rm --volume=/srv/neo4j/data:/data --volume=/srv/neo4j/backups:/backups neo4j/neo4j-admin:2026.09.0 neo4j-admin database dump neo4j --to-path=/backups

docker start neo4j

Repeat the docker run for system. For a named volume use --volume=neo4j_data:/data. Neo4j's examples add --interactive --tty; leave those out in cron. To restore, run neo4j-admin database load --from-path=/backups --overwrite-destination=true neo4j the same way with the container stopped. NEO4J_AUTH has no effect on a /data that already holds users, so a loaded system decides the passwords.

Enterprise: online backups

Enterprise runs a backup service, on by default and listening on 127.0.0.1:6362 (server.backup.listen_address). It backs up while Neo4j runs:

sudo -u neo4j neo4j-admin database backup --to-path=/var/backups/neo4j "*"

"*" takes every database, system included. The first run writes a full .backup file per database and later runs write differential ones (--type=FULL forces a full one); each backup includes the users and roles tied to that database unless --include-metadata says otherwise. Restore with the database stopped, naming the newest file of the chain: neo4j-admin database restore --from-path=/var/backups/neo4j/neo4j-2026-10-04T02-15-00.backup --overwrite-destination=true neo4j. Restoring under a new name needs CREATE DATABASE afterwards. If you open the port to other machines, firewall it: anyone who reaches it can copy the database.

Moving between versions

• Load a dump into the same version or newer. Neo4j does not support downgrades.
• 5.26 LTS is a checkpoint: anything older moves to 5.26 before any 2025 or 2026 release.
• From 4.4, dump with the old syntax (neo4j-admin dump --database=neo4j --to=/dumps/neo4j.dump), load it into 5.26, then run neo4j-admin database migrate neo4j with the database stopped. Neo4j's migration steps leave out the 4.4 system database, so recreate users.
• Enterprise databases default to the block store format, which Community can't use. To move one to Community, migrate it to aligned on Enterprise first (--to-format=aligned), then dump it.

Moving the whole server as well? See migrating to a new provider.

Common errors

Frequently asked questions

Can I back up Neo4j Community without stopping it?

No. In Community Edition neo4j-admin database dump runs only on a stopped DBMS. Online backups are an Enterprise Edition feature, and Neo4j does not support copying the store files while it runs.

Does a Neo4j dump include users and passwords?

Not the dump of your graph database. Users, roles and privileges are in the system database, so dump system as well and load it when you restore.

Where does neo4j-admin database dump save the file?

In the --to-path directory, named after the database: neo4j.dump for neo4j. Without --to-path it uses server.directories.dumps.root, which defaults to data/dumps.

Can I load a Neo4j 5 dump into Neo4j 2026?

Yes, from 5.26 LTS to any 2025 or 2026 release. Older versions must go through 5.26 first, and Neo4j does not support loading into an older version.

How do I check a Neo4j backup is good?

Run neo4j-admin database check with --from-path set to the dump's directory. It exits 0 with no report when the copy is consistent, and writes an inconsistencies report when it isn't.