n8n 3.0 requires Docker: why your self-hosted install needs a migration, not an update

n8n has published the list of changes coming in version 3.0, scheduled for October 2026. One of them changes the routine of everyone running the tool on their own server: self-hosted n8n will require a Docker-based deployment. Installations run via npm or npx n8n will no longer be supported.

If your automation runs today on Node.js with n8n installed through npm — on a VPS, on a server inside the company, or even on a machine that stays on in the office — the path you used for every previous upgrade stops existing. There will be no update command that solves it. There will be a migration.

The distinction matters, because the risks are very different.

An update keeps the same environment and swaps the software version. A migration moves data, credentials, and configuration from one environment to another. That movement is where things get lost.

What changes beyond Docker

The container requirement is the most visible change, but not the only one. Version 3.0 also retires nodes, features, and behaviors that still show up in plenty of older workflows, and it tightens the tool’s security defaults. In practice, that means a container can start without a single error and still hold workflows that quietly stopped working, because they depend on a component that no longer exists. And a workflow that fails silently tends to be discovered by the client, not by the team.

We will cover that part in a follow-up post, item by item, with the recommended replacement for each removed component and what to review in existing workflows.

Why “just run a docker compose” is riskier than it looks

The internet is full of tutorials that install n8n in three lines. They work very well when you are starting from scratch. The problem is applying that same recipe to an environment already in production, with live integrations and accumulated history.

A few things that routinely break rushed migrations:

The encryption key. n8n encrypts saved credentials with a key generated at install time. If the container starts with a new key, every existing credential becomes unreadable. In practice, that means manually reconnecting each integration: email accounts, CRMs, payment gateways, internal APIs. In mature environments, that is dozens of them.

The database. npm installs typically use SQLite, written to a file in the user’s home directory. If the volume is not mapped correctly, the container comes up clean — interface working, and not a single workflow inside. That is the scenario that scares people most: everything looks fine, and the entire history is gone.

The environment variables. Settings that live today in a systemd unit, a process manager, or the shell itself have to be carried over to the compose file. Timezone, execution retention policy, concurrency limits, and the public URL all belong on that list.

The webhooks. External services store the URL you registered with them. If the public address changes during the migration, or the reverse proxy is reconfigured carelessly, triggers stop arriving without raising any visible error in n8n.

Whatever lived outside n8n. Community nodes installed via npm, helper scripts, files read from or written to local folders, and directory permissions all change context inside a container. None of it migrates on its own.

The migration as a chance to review

Changing how the tool runs forces you to open up the environment. It is a good moment to fix decisions made back when the automation was still an experiment and never revisited since.

Moving off SQLite to PostgreSQL is the highest-impact change. SQLite is fine early on, but it struggles with concurrency, grows unchecked as execution history piles up, and makes backup and restore more fragile. PostgreSQL handles volume, allows consistent backups without stopping the service, and is a prerequisite for running n8n in queue mode with separate workers once execution counts justify it.

Other items worth putting in scope:

• Automated backup and, above all, restore testing. A backup that has never been restored is an assumption, not a guarantee.
• A staging environment separate from production, to validate changes before shipping them.
• Version control for workflows, with a record of who changed what.
• Monitoring and alerting for failed executions, instead of relying on someone opening the screen to check.
• An update policy with pinned versions, so a latest image never changes the environment’s behavior without warning.

What a well-run migration looks like

The playbook is well known and holds no mystery, but it does demand method:

1. Inventory of the current environment: version in use, active credentials, production workflows, deprecated nodes still in use, integrations that depend on a public URL, and configuration variables.
2. Parallel replica in containers, with the database migrated and the encryption key preserved, without touching the current install.
3. Validation workflow by workflow, including the scheduled ones that may not surface in a quick test.
4. Fixing removed nodes and the affected expressions, comparing behavior against the old version.
5. A planned cutover, in a defined window, with the old environment left intact.
6. A rollback plan written beforehand, not improvised mid-flight.

Order matters. Production is only switched off after the new install has proven it works.

Where a specialized consultancy fits

If your n8n runs two simple workflows and no critical credentials, a weekend and a tutorial will probably do the job.

If it underpins operations, customer support, billing, or service delivery, the math changes. The cost of a bad migration is not server time: it is the order that was never processed, the lead that never reached the CRM, the invoice that was never sent, and the week of work spent reconnecting integrations one by one.

At n8nscale we work at exactly that point. We run the migration to Docker preserving credentials and history, review the workflows that depend on deprecated nodes, move the database to PostgreSQL when the scenario justifies it, and leave backup, monitoring, and the update process documented. You get a working environment, and your operation keeps running throughout.

October feels far away. But taking inventory of what you have today is the part nobody wants to do in a hurry.

Want to know what shape your environment is in before 3.0? Talk to n8nscale and get an assessment of your current install, with the risk points mapped out.

---

Official source for the changes: n8n Docs — v3.0 Breaking changes