How to Update n8n Without Breaking Your Workflows
By Tushar Khatri
If you self-host n8n, updates are not optional. Knowing how to update n8n safely is the difference between a five-minute maintenance window and a weekend spent rebuilding workflows from memory. n8n ships new releases on a fast, roughly weekly cadence, so the version you installed a few months ago is already well behind on features, bug fixes, and security patches. The good news: an n8n upgrade is a simple, repeatable process once you follow a few rules. This guide walks through the full procedure for Docker and Docker Compose, what to verify afterward, and how to recover when an update goes sideways.
Why Updating n8n Matters
Every n8n release brings some mix of new nodes, improvements to existing integrations, editor enhancements, performance work, and security fixes. Because third-party APIs change constantly, node updates are not just nice-to-haves. A workflow that talks to an external service can quietly degrade if the underlying node falls too far behind what the API expects.
Security is the other half of the story. A self-hosted n8n instance holds credentials for every service your workflows touch: databases, CRMs, payment providers, email accounts. Running an old version means running with known, published vulnerabilities. Staying reasonably current is one of the cheapest security wins available to you.
There is also a practical maintenance argument. Small, frequent updates are low-risk and easy to reason about. Letting versions pile up turns a routine n8n upgrade into a migration project, and migration projects are where workflows break.
The Golden Rule: Back Up Before Every Update
Before touching a single container, take a backup. Not sometimes. Every time.
The reason is specific to how n8n works. On startup, n8n runs its own database migrations to bring the schema in line with the new version. These migrations are one-way. Once a newer version has migrated your database, an older version cannot read it. That means your pre-update backup is not just a safety blanket, it is the only rollback path you have.
A complete pre-update backup covers three things:
- The data volume. This holds your SQLite database (if you use the default), binary data, and instance files.
- The encryption key. n8n encrypts stored credentials with this key. Without it, a restored database is full of credentials you cannot decrypt.
- A database dump. If you run Postgres, take a proper dump rather than relying on volume snapshots alone.
If you have not set this up yet, the full procedure is covered in our guide to n8n backup and restore. Do that first, then come back. Seriously.
Pin a Version Tag, Do Not Run latest
Before we get to the update commands, one piece of housekeeping. Because n8n releases so frequently, running the latest tag means any container restart can silently pull a new version and migrate your database when you least expect it. That is exactly the kind of surprise this guide exists to prevent.
Pin an explicit version tag in your Docker or Compose configuration. Updates should happen when you decide, with a backup already taken, not whenever Docker happens to re-pull an image.
How to Update n8n With Docker Compose (Step by Step)
This is the recommended flow for anyone running n8n via Docker Compose, which should be most production self-hosters. If you have not containerized your setup yet, our production docker compose setup guide covers getting there.
Step 1: Read the release notes
Before choosing a target version, read the release notes and the breaking-changes list for every version between your current one and the target. This takes five minutes and catches the vast majority of avoidable incidents: renamed settings, changed node behavior, deprecated features. If you are jumping multiple major versions, plan to step through them rather than leaping straight to the newest release.
Step 2: Take your backup
Volume, encryption key, database dump. Covered above, not skippable.
Step 3: Update the image tag
Edit your docker-compose.yml and change the pinned version tag on the n8n image to your target version.
Step 4: Pull the new image
docker pull docker.n8n.io/n8nio/n8n:<new-version>
Replace <new-version> with your target tag. Pulling ahead of time keeps the actual switchover fast.
Step 5: Recreate the container
docker compose up -d
Compose notices the changed image tag and recreates the n8n container. Your data is safe through this step because it lives in volumes, not in the container itself. The container is disposable; the volumes are not.
On startup, the new version runs its database migrations automatically. Watch the logs while this happens:
docker compose logs -f n8n
A clean startup with migrations completed means the mechanical part of the update is done. Now comes the part most people skip.
What to Check After an n8n Upgrade
Do not declare victory just because the container is running. Verify the things that actually matter:
- Open the editor. Log in, confirm the UI loads, and check that your workflows and credentials are all listed. The version number in the UI should match your target.
- Run one credentialed workflow. Pick a workflow that uses stored credentials and execute it manually. This confirms both that executions work and that your encryption key still decrypts credentials correctly.
- Check your webhooks. Trigger a webhook-based workflow from the outside, or send a test request to a webhook URL. Webhook registration is the piece most likely to misbehave after infrastructure changes, and a workflow that never fires fails silently.
- Check your community nodes. Community-built nodes are maintained on their own schedules and can lag behind new n8n versions. After upgrading, open workflows that use community nodes and confirm they still load and execute. If one is broken, check whether the node has a newer release before assuming n8n is at fault.
Ten minutes of verification here saves you from discovering a broken automation three days later when a customer asks why their order confirmation never arrived.
When Things Break: How to Roll Back
Here is the part that surprises people. Rolling back an n8n update is not as simple as changing the image tag back and restarting.
Remember those one-way database migrations? Once the new version has migrated your database, the old version will refuse to work with it, or worse, misbehave against a schema it does not understand. Re-tagging the image does nothing about the database state.
A real rollback looks like this:
- Stop the n8n container.
- Restore the pre-update backup: the database dump (or volume) and the encryption key, exactly as they were before the upgrade.
- Set the image tag back to your previous version.
- Bring the stack up and verify, using the same checklist as above.
This is why the backup rule is non-negotiable. Without a pre-update backup, there is no rollback, only forward through whatever broke. With one, a failed update costs you a restore and a retry instead of a crisis.
How Far Behind Is Too Far?
Given the weekly release cadence, nobody expects you to update every single week. But the risk of an n8n upgrade grows with the distance you are jumping. Skipping a few minor versions is usually uneventful. Jumping across one or more major versions in a single step is where breaking changes stack up and interact in ways release notes alone will not fully prepare you for.
Two rules of thumb:
- Update on a schedule. Monthly is a reasonable rhythm for most self-hosted instances. Frequent small updates keep each jump boring.
- When far behind, step through majors. If you are several major versions back, upgrade one major version at a time, verifying at each stop, rather than leaping straight to the newest release. It takes longer but each step is diagnosable. A giant single jump that fails leaves you guessing which of a dozen changes broke you.
The Zero-Effort Alternative
Everything above is manageable, but it is recurring work: reading release notes, taking backups, verifying workflows, keeping a rollback plan warm. If you would rather spend that time building automations instead of maintaining the machine that runs them, Hosto managed n8n handles updates automatically on dedicated VMs, with backups taken before every upgrade. You get current versions without ever thinking about migrations or rollback paths.
For everyone self-hosting, the playbook stands: back up, pin versions, read the notes, update deliberately, verify thoroughly.
FAQ
How do I update n8n in Docker?
Back up your data volume, encryption key, and database first. Then pull the new image with docker pull docker.n8n.io/n8nio/n8n:<new-version>, update the version tag in your compose file, and run docker compose up -d to recreate the container. n8n runs its database migrations automatically on startup. Verify by opening the editor, running a credentialed workflow, and testing a webhook.
Will updating n8n delete my workflows?
No. Your workflows, credentials, and execution history live in Docker volumes and your database, not in the container. Recreating the container with a new image leaves that data intact, and n8n migrates the database schema on startup. The backup you take beforehand is insurance against a failed migration, not because updates routinely wipe data.
Can I downgrade n8n after an update?
Not by simply switching back to the old image tag. n8n's database migrations are one-way, so once a newer version has migrated your database, older versions cannot use it. To downgrade, restore your pre-update backup (database and encryption key), set the previous image tag, and start the stack again. This is why backing up before every update matters.
Should I use the latest tag for n8n in production?
No. n8n releases roughly weekly, so latest means any container restart can pull a new version and run irreversible database migrations without warning. Pin a specific version tag and update deliberately, with a fresh backup, on your own schedule.