Updating n8n means pulling a new image or package version and letting n8n run its own database migrations on startup. The safe order is: back up the database, read the breaking-changes notes for every major version between your current one and the target, pin the exact image tag you are moving to instead of trailing latest, and leave the encryption key untouched. With Docker Compose that is docker compose pull then docker compose up -d. With npm it is npm update -g n8n. On a hosted instance, updating is usually a dashboard action rather than a command run over SSH.
n8n ships new versions often, and most of them are quiet, unattended updates. The versions worth slowing down for are the ones that touch the workflow data model, change a node’s parameters, or drop support for an old runtime, and those are exactly the ones a changelog skim will not catch if you are only reading the version number.
The steps below apply whether n8n is running in a container, installed as a global npm package, or managed for you.
Table of contents
- What Actually Changes When You Update n8n
- Before You Update: Back Up the Database
- Before You Update: Read the Breaking Changes
- Before You Update: Pin the Tag, Leave the Encryption Key Alone
- Updating with Docker Compose
- Updating with npm
- Updating on a Hosted or Managed Instance
- Rollback and Major-Version Notes
- How this fits the rest of the stack
- FAQ
What Actually Changes When You Update n8n
An n8n update is two things happening at once: a new version of the application code, and a set of database migrations that run automatically the first time the new version starts. Workflows, credentials and execution history live in the database (SQLite by default, or Postgres or MySQL if you configured one), and the migration step rewrites that schema to match the new code. This is why an update is not just swapping a binary, it is a one-way write to data you cannot afford to lose.
Most releases are patch or minor versions and change little beyond bug fixes and new nodes. Major versions are where node behaviour changes and the migration does real structural work. Treat every major-version jump as its own update, not a number to skip past.
Before You Update: Back Up the Database
Migrations in n8n are forward-only. There is no built-in undo, so the backup you take before updating is the only way back if something goes wrong. What to back up depends on the backend: a Postgres or MySQL database gets a dump, a SQLite setup gets a copy of the database file, and the encryption key gets copied alongside it either way.
- Postgres: pg_dump the n8n database to a file outside the container
- MySQL: mysqldump the same way, with —single-transaction
- SQLite: stop n8n, copy the .sqlite file, restart
- Note the exact n8n version you backed up from, you will need it if you roll back
Before You Update: Read the Breaking Changes
Every major n8n release publishes a breaking-changes note, and it is worth reading in full rather than skimming for your own node types, since a change to how expressions evaluate or how a trigger authenticates can affect a workflow you forgot existed. If you are jumping more than one major version, read the notes for each version in between, not just the target.
The official release notes list what changed per version, including deprecated nodes and renamed environment variables. Cross-reference against your own workflow list before you touch anything.
It is the twenty minutes that separates an update from an incident. Skipping it does not usually cause a problem, but the one time it does, the failure shows up as a workflow silently doing the wrong thing rather than a clean error you can act on.
Before You Update: Pin the Tag, Leave the Encryption Key Alone
If your Docker Compose file points at n8nio/n8n:latest, you do not control which version you get on the next pull, you get whatever was tagged latest that day, which might be several majors ahead of what you tested. Pin an explicit version (n8nio/n8n:1.64.0) and move it deliberately, one release at a time if you are behind by more than a major version.
The encryption key, set via N8N_ENCRYPTION_KEY or stored in n8n’s config directory, decrypts every saved credential. It is generated once and should never be regenerated or lost. An update that changes the volume mount or environment without carrying the key across turns every stored credential unreadable, with no recovery path except re-entering them by hand.
Updating with Docker Compose
This is the most common self-hosted path, and the update itself is two commands once the backup is done. Edit the image tag in your compose file first, to the specific version you decided on after reading the release notes.
docker compose pull n8n
docker compose up -d n8n
docker compose logs -f n8nWatch the logs for the migration step completing before you consider the update done. If the container restarts in a loop, the fastest recovery is reverting the tag in the compose file and restoring the database backup.
Updating with npm
A non-Docker self-hosted instance installed with npm install -g n8n updates the same way any global package does, followed by a service restart. There is no automatic rollback here, so the database backup is doing the same job it does in the Docker path.
npm update -g n8n
n8n --version
sudo systemctl restart n8nCheck the Node.js version required by the target n8n release before updating. Major n8n versions periodically raise the minimum Node version, and an update that succeeds but then fails to start is usually a Node mismatch, not a migration failure.
Updating on a Hosted or Managed Instance
n8n Cloud updates itself on a schedule you do not control, with its own maintenance notices. On a managed platform that runs n8n as an application rather than a service you SSH into, the update is a redeploy against a newer image tag from a dashboard, with the same backup-first logic applying even though you never touch a terminal.
The backup step does not disappear just because the update button does not ask for a database dump. It happens on whatever schedule the managed database itself runs, and it is worth confirming that schedule covers a point shortly before you click update, rather than assuming it does.
Rollback and Major-Version Notes
Because migrations are one-way, rolling back means restoring the database backup taken before the update and pointing the container or package back at the previous version tag, not just reverting the code and hoping the newer schema still works with it.
- 0.x to 1.x carried a credential re-encryption step, do not skip the release notes for that jump specifically
- Later majors have dropped support for old community nodes with no migration path other than replacing the node
- Keep at least one full backup that predates the last major version you crossed, not just the most recent one
How this fits the rest of the stack
n8n updates are routine until the version you skip turns out to be the one with a migration worth reading first. Running it yourself means owning the server, the tag, and the backup schedule. Managed n8n on a $6 Basic plan updates from a dashboard button instead, with a managed database sitting next to it for the backup this process depends on. What that costs together is what the RunxBuild hosting calculator adds up.
Useful related references:
- n8n Google Sheets Integration: Auth, Operations, and the Row-Update Trap
- n8n vs Make: Where the Complexity Goes
- n8n Use Cases: What It Is Genuinely Good At, and What It Is Not
- Docker services on RunxBuild
FAQ
How do I update n8n running in Docker Compose?
Back up the database first, since n8n’s migrations run automatically and are not reversible. Then pin the target version in your compose file instead of using latest, run docker compose pull followed by docker compose up -d, and watch the logs until the migration step finishes before considering the update complete.
How do I update n8n installed with npm?
Run npm update -g n8n, then restart the process with your service manager, such as systemctl restart n8n or a pm2 reload. Check the Node.js version the new n8n release requires beforehand, since major versions periodically raise the minimum supported Node version and a mismatch will stop the service from starting.
Does updating n8n break my workflows?
Usually not for patch and minor releases. Major versions can deprecate nodes, change expression behaviour, or alter how credentials are stored, which is why reading the breaking-changes notes for every major version you cross matters more than the release notes for the specific version you land on.
How do I roll back an n8n update?
Restore the database backup you took before updating and point the container or package back at the previous version tag. Because n8n’s migrations only run forward, reverting the code without restoring the database usually leaves a schema the older version cannot read.