Ctrlk
ForumChangelog
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Back up and restore

Back up a self-hosted n8n instance so you can recover from data loss, roll back a failed update, or move to a new server. A complete backup includes more than the CLI export commands produce on their own. This page explains what a complete backup contains, what the CLI --backup flag exports, and how to restore each kind of backup.

What a complete backup includes

A complete backup of a self-hosted n8n instance consists of two parts:

  • The .n8n user folder, ~/.n8n by default. It holds the config file, which stores the credential encryption key. With the default SQLite database, it also holds the database file itself. If binary data or execution data uses the filesystem storage mode, it holds that data too.

You can change the folder's location with the N8N_USER_FOLDER environment variable: n8n uses the .n8n subfolder of the path you set.

  • Your external database, if you use PostgreSQL instead of the default SQLite. Back it up with your database's own tooling. The .n8n folder is still part of the backup, because credentials in the database are encrypted with the key it holds.

If you configured external storage for binary data or execution data, such as S3 or Azure Blob Storage, back that storage up as well. If binary data or execution data is stored on a custom filesystem path, include that location in your backup too. If you load custom nodes from directories set in the N8N_CUSTOM_EXTENSIONS environment variable, back those directories up as well: a restored instance without them is missing the nodes its workflows reference.

With the default SQLite database, stop n8n before copying the .n8n folder. Copying the database file while n8n is writing to it can produce an inconsistent backup. If you can't stop n8n, use a tool that takes a consistent snapshot of the SQLite file instead.

If you run n8n in Docker, the .n8n folder lives in the n8n_data volume, mounted at /home/node/.n8n. For more information about persistent data in Docker, see Install with Docker.

The encryption key is required to restore credentials

n8n saves credentials to the database in encrypted form. Without the encryption key from the config file, or a custom N8N_ENCRYPTION_KEY, a restored database or encrypted credential export can't be decrypted. For more information, see Set a custom encryption key.

n8n recommends taking a full backup before updating. For update procedures, see Update n8n.

Back up workflows and credentials with the CLI

You can export workflows and credentials to JSON files using the Server CLI:

n8n export:workflow --backup --output=backups/workflows/
n8n export:credentials --backup --output=backups/credentials/

The --backup flag sets --all --pretty --separate, so each workflow and credential is written as a separate, readable JSON file.

Use a different output directory for each command. import:credentials --separate currently fails when the input directory also contains workflow files. This is a known issue.

If you run n8n in Docker, a backups/ directory inside the container isn't persisted: only the .n8n folder is in a volume. Bind-mount a host directory for your backups, or copy the exported files out of the container before recreating it.

What a CLI backup doesn't contain

The --backup exports contain workflows and credentials only. They don't include:

  • Users and their roles. After importing into a fresh instance, n8n shows the owner setup screen again, and the first person to complete it becomes the owner.

  • Execution history and logs.

  • Variables.

  • Instance settings, including the encryption key.

This means a CLI backup is enough to move workflows between instances, but not enough to recover a full instance on its own. For that, keep a backup of the .n8n folder and the external database as described in What a complete backup includes.

Restore

Restore workflows and credentials

Import the files from your CLI backup. On a fresh instance, complete the owner setup first: the import commands need an existing user, and imported credentials need an owner. If your instance has multiple users or projects, use --userId or --projectId to assign the imported credentials.

Exports include the original workflow and credential IDs. If the target instance already has items with the same IDs, they're overwritten. Imported workflows are deactivated by default. Activate them in the UI after importing, or pass --activeState=fromJson to restore each workflow's exported active state, which only works in queue or multi-main mode. For the full list of flags and caveats, see Use the command line.

To restore credentials, the importing instance must be able to decrypt them. You have two options:

  • Use the same encryption key as the exporting instance. Restore the config file to the .n8n folder, or set the same N8N_ENCRYPTION_KEY environment variable.

  • Export with the --decrypted flag, which writes credentials in plain text.

Sensitive information

A --decrypted export contains all credential data in plain text. Store it with the same care as the credentials themselves, and delete it once the restore is complete.

Restore the full instance

To restore a complete instance:

  1. Stop n8n.

  2. Restore the .n8n folder to its original location, plus any custom-node directories you configured with N8N_CUSTOM_EXTENSIONS.

  3. Restore your PostgreSQL database from its backup, if you use one.

  4. Restore your deployment configuration: the environment variables for your database connection, a custom N8N_ENCRYPTION_KEY if you use one, and any external storage settings. Without them, a restored instance can't reach its database or decrypt its data.

  5. Start n8n.

With the default SQLite database, the .n8n folder holds everything needed to recover the instance: the SQLite database file, which contains users, settings, and execution data, the encryption key, and, on filesystem storage modes, binary and execution data. With PostgreSQL, the .n8n folder still holds the encryption key, and the database backup holds the rest.

Related content

Related resources

PreviousVisualize metrics with Grafana
NextUpdate n8n

Last updated

Was this helpful?