n8n ships a new minor version most weeks, following semantic versioning, and self-hosters have two real Docker channels to choose from: the default stable tag and the next tag, which tracks the most recent, less-tested release.
Fast release cadence is good for a product and mildly stressful for whoever is responsible for a self-hosted instance nobody wants to wake up broken. n8n’s release model is straightforward once you know where to look, and the actual risk in upgrading is almost always process, not the software itself.
Table of contents
- How n8n’s versioning actually works
- Stable versus next: the two Docker channels
- Reading release notes without drowning in them
- The lessons from the 1.0 migration
- Upgrading a self-hosted Docker install safely
- SQLite by default, Postgres when you outgrow it
- RunxBuild’s take: managed n8n skips the upgrade babysitting
- How this fits the rest of the stack
- FAQ
How n8n’s versioning actually works
n8n follows semantic versioning: MAJOR.MINOR.PATCH. A MAJOR bump signals incompatible changes that may need action on your part. MINOR versions add functionality without breaking existing workflows. PATCH releases are backward-compatible bug fixes.
In practice, most weeks bring a new minor version with a batch of node improvements and small features, not a rewrite. Reading the version number tells you roughly how much attention a given upgrade deserves before you assume it’s routine.
n8n publishes entries as merged pull requests are reviewed and rolled out, which means a feature landing in the release notes doesn’t always mean it’s live for every instance immediately. Some ship behind a feature flag you opt into, and Cloud and self-hosted instances don’t always get a given change on the same day. Don’t assume a documented feature is active in your instance until you’ve actually checked.
Stable versus next: the two Docker channels
n8n publishes two meaningfully different Docker tags. Pulling the image with no tag gets you the stable channel, meant for production. Pulling with the next tag gets you the most recent build, which can be genuinely unstable and is meant for people who want to try upcoming changes early.
# Stable, for production
docker pull n8nio/n8n
# Pinned to an exact version
docker pull n8nio/n8n:1.81.0
# Most recent, unstable
docker pull n8nio/n8n:nextFor a self-hosted instance running real workflows, stay on stable and pin an exact version tag rather than tracking the bare tag automatically. Floating on “whatever stable currently means” is how an unattended update becomes a surprise.
The next tag is genuinely useful, just not for production. If you maintain custom nodes or depend on an integration that’s actively being changed upstream, running next in a throwaway staging instance is the cheapest way to catch a breaking change before it reaches stable and your actual workflows.
Reading release notes without drowning in them
n8n actually maintains three separate release surfaces, and knowing which one to read saves time. The curated changelog gives a narrative summary of the headline features. The release notes page lists every feature-level update per version, generated from merged pull requests. GitHub Releases has the full diff, down to the bug fixes and minor internal changes.
- Changelog: quick scan for whether anything big shipped
- Release notes: the feature list, useful when a specific node behavior changed
- GitHub Releases: the full detail, useful when something breaks and you need to know exactly what changed
For a routine weekly upgrade, the release notes page is usually enough. Save the GitHub Releases deep-dive for when a workflow actually breaks after an update and you need to find the specific pull request responsible.
An RSS feed is also published for the release notes, which is worth subscribing to if you’d rather have new entries land in a reader than remember to check a page. It’s a small habit that pays for itself the first time it flags a breaking change before your scheduled upgrade window.
The lessons from the 1.0 migration
n8n’s move to its 1.0 line changed enough underlying behavior that workflows built against older defaults needed real attention, not just a version bump. Node versioning was tightened, some default behaviors changed, and workflows that depended on the old defaults silently produced different results after upgrading rather than failing loudly.
The lesson that carries forward past that specific migration: a MAJOR version number is the signal to actually read the notes rather than assume compatibility, and node-level version pinning inside a workflow is what protects you from a future default change breaking something that currently works.
It’s also why a staging instance is worth the modest extra hosting cost if you’re running anything business-critical through n8n. Restoring a backup after a failed production upgrade works, but it costs downtime you’d rather not explain to whoever depends on the workflow that broke.
Upgrading a self-hosted Docker install safely
The mechanics of an update are simple. The discipline that keeps it safe is doing these steps in order and not skipping the backup because the last ten upgrades went fine.
- Back up the .n8n volume and, if you’re on Postgres, the database itself. Encryption keys and instance settings live in .n8n even when workflow data lives in Postgres.
- Read the release notes for every version between your current one and the target, not just the latest entry.
- Pull the specific version tag you’re targeting rather than the bare stable tag.
- Test the new image against a copy of your instance, or at minimum a non-critical workflow, before replacing production.
- Stop, remove, and restart the container with the new image; with Docker Compose, that’s a pull, down, and up.
docker compose pull
docker compose down
docker compose up -dSQLite by default, Postgres when you outgrow it
A detail that surprises new self-hosters: n8n uses SQLite by default for credentials, executions, and workflow data. Postgres is supported and configured through environment variables, and it’s the right move once you have more than a single instance or executions volume that makes a single SQLite file a bottleneck.
Either way, keep the .n8n directory persisted. Even on Postgres, it holds the encryption key and instance logs, and losing it can mean losing access to stored credentials even though the workflow data itself survives.
There’s no hard rule for when to make the switch, but a rough one holds up: if you’re running more than a handful of scheduled workflows firing concurrently, or you’re seeing the database file itself become a bottleneck under load, that’s the signal to move to Postgres rather than waiting for a visible failure.
Switching later is a supported migration path, not a rebuild. n8n reads the database type from environment variables at startup, so moving from SQLite to Postgres is mostly a matter of standing up the new database, pointing the environment variables at it, and letting the instance run its migrations on first boot.
RunxBuild’s take: managed n8n skips the upgrade babysitting
None of the above is hard, but it is one more operational responsibility on a self-hoster’s plate: a server to patch, TLS to renew, backups to verify, and a release cadence to track every week. It’s real work, and it’s the same work regardless of how many workflows you’re actually running.
How this fits the rest of the stack
If the appeal of n8n was the workflows, not the server maintenance behind them, RunxBuild runs n8n as a managed tool with its own plan, custom domains, environment variables, autoscaling, and logs, starting on the $6 Basic plan, so the upgrade discipline above becomes something the platform handles rather than something on your calendar. The RunxBuild hosting calculator shows what n8n plus a managed Postgres instance beside it actually costs before you commit.
If tracking tags and backing up volumes before every upgrade sounds like a second job, managed n8n can be created from the RunxBuild dashboard with a Postgres alongside it.
Useful related references:
- n8n Rate Limit Node: Throttling Requests Without Losing Data
- Open Source Workflow Automation Tools Worth Actually Self-Hosting
- No-Code Automation Platform: What You’re Actually Buying
- Docker services on RunxBuild
FAQ
What is the difference between n8n’s stable and next Docker tags?
The stable channel, pulled with no tag or a pinned version number, is meant for production and is what most releases settle into. The next tag tracks the most recent build, which can include unreleased changes and genuine instability, and is meant for testing upcoming features early.
How often does n8n release new versions?
n8n ships a new minor version most weeks, following semantic versioning. Patch releases for bug fixes can land even more frequently, while major versions with breaking changes are comparatively rare.
Is it safe to auto-update a self-hosted n8n instance?
It’s safer to pin an exact version and upgrade deliberately than to float on an automatically updating tag. Read the release notes for every version between your current one and the target, and back up the .n8n volume and any external database first.
Does n8n use SQLite or Postgres by default?
SQLite by default, for credentials, executions, and workflow data. Postgres is fully supported and configured through environment variables, and is the better choice once a single SQLite file becomes a bottleneck for concurrent executions.
What should I back up before upgrading self-hosted n8n?
The .n8n directory, which holds the encryption key, instance settings, and logs regardless of which database you use, plus your Postgres database itself if you’re not on the default SQLite storage.