> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/deploy/host-n8n/keep-n8n-running/backup-and-restore.md).

# Back up and restore

Back up and restore a self-hosted n8n instance, including what CLI backups contain, what they miss, and how to recover a full instance.

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](/deploy/host-n8n/install-options/install-with-docker.md).

{% hint style="info" %}
**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](/deploy/host-n8n/configure-n8n/basic-configuration/configuration-examples/set-a-custom-encryption-key.md).
{% endhint %}

n8n recommends taking a full backup before updating. For update procedures, see [Update n8n](/deploy/host-n8n/keep-n8n-running/update-n8n.md).

## Back up workflows and credentials with the CLI

You can export workflows and credentials to JSON files using the [Server CLI](/deploy/host-n8n/configure-n8n/use-the-command-line.md):

```bash
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](https://github.com/n8n-io/n8n/issues/37814).

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](#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.

```bash
n8n import:workflow --separate --input=backups/workflows/
n8n import:credentials --separate --input=backups/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](/deploy/host-n8n/configure-n8n/use-the-command-line.md).

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.

{% hint style="warning" %}
**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.
{% endhint %}

### 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

* [Keep n8n running](/deploy/host-n8n/keep-n8n-running.md): guides for operating a self-hosted n8n instance.
* [Use the command line](/deploy/host-n8n/configure-n8n/use-the-command-line.md): the full Server CLI reference, including all export and import flags.
* [Set a custom encryption key](/deploy/host-n8n/configure-n8n/basic-configuration/configuration-examples/set-a-custom-encryption-key.md): how to provide `N8N_ENCRYPTION_KEY` explicitly.
* [Choose n8n's database](/deploy/host-n8n/configure-n8n/choose-n8ns-database.md): SQLite and PostgreSQL configuration.
* [Update n8n](/deploy/host-n8n/keep-n8n-running/update-n8n.md): update procedures for npm and Docker installations.