Skip to main content

n8n 3.0: Release Date, Breaking Changes and How to Upgrade

n8n 3.0 had no installable release on 13 October 2026. Every documented breaking change by who it affects, the Docker-only switch, and how to upgrade safely.

Founder of IImagined.ai

Published
Oct 1, 2026
Updated
Oct 13, 2026
Reading time
12 min read
Quick answer

n8n 3.0 could not be installed on 13 October 2026: n8n's docs say it has been released, but the newest stable release was 2.43.4 and no 3.x build had been published. Self-hosted 3.0 runs only from n8n's official Docker image, so npm and npx installs must move to Docker on their current 2.x version first. 3.0 also removes a long list of older nodes such as Function, Item Lists and Cron, drops version 1 of the AI Agent node, renames the binaryData folder to storage, turns off unverified community nodes and Chat Hub by default, and cuts the Code node task timeout to 60 seconds. Before upgrading, open Settings, then Migration Report, back up the .n8n folder and database, pin your image version and test on a copy.

n8n 3.0 is documented but could not be installed when this page was last checked, on 13 October 2026. n8n's breaking-changes page opens with "n8n 3.0 has been released", yet the newest stable release that day was 2.43.4, with no 3.x version on GitHub, npm or Docker Hub. The change most people must act on is that self-hosted 3.0 runs only from the official Docker image.

Checked on 13 October 2026 against n8n's 3.0 breaking-changes page, its v3 development guide, GitHub releases, the Docker install page, Docker Hub and npm. First published on 1 October 2026, when the breaking-changes page still read "scheduled for October 2026". The page has gained detail since, so read it again on the day you upgrade.

n8n 3.0 release date: is it out yet?

Not as an installable release on 13 October 2026, and n8n has not named a day. Its v3 guide on GitHub says "~October 2026" and describes 3.0 as "an operational release" of breaking changes, removals and legacy cleanup, "not a big-bang feature launch".

Status on 13 October 2026
n8n 3.0Docs page says released. No 3.x release on GitHub, npm or Docker Hub
Current stable2.43.4, published 12 October 2026
Current beta2.44.0, published 13 October 2026
n8n on npm2.43.4. 3.0 will not publish a runnable package there
Test imagesv3-rc (newest release candidate), v3-rc-20261012.1 (fixed), v3-nightly (daily)
1.xStill patched: 1.123.84 on 8 October 2026

The v3 guide offers the test images for trials in Docker or Kubernetes before release and adds: "Do not use them in production." To test one, pin a fixed tag such as v3-rc-20261012.1, because v3-rc and v3-nightly move. Each Monday's nightly is retagged as a release candidate.

The order to do the work in
  1. Now, on 2.x
    Update to the newest 2.x and open the Migration Report

    It lists the workflows and settings 3.0 affects on your instance.

  2. Now, on 2.x
    Move npm or npx installs to Docker

    Same version, same database, same encryption key. Change one thing at a time.

  3. Before upgrade day
    Replace removed nodes and fix flagged settings

    Every replacement node already exists in 2.x.

  4. Before upgrade day
    Back up and test on a copy

    Restore the backup into a second Compose project and try a release candidate there.

  5. Upgrade day
    Pin the 3.x version, pull and start

    Only once 3.0 is a stable release.

  6. After
    Run your key workflows and watch Executions

    Keep the backup until a full week of runs looks normal.

n8n 3.0 breaking changes by who they affect

Find your row first. Most instances are touched by two or three of these, not all of them.

WhoWhat breaksFirst step
Self-hosted on npm or npxNo longer supportedMove to Docker on your current 2.x version
Self-hosted on DockerRenamed storage folder, removed variables, stricter defaultsFix mounts and set the values you rely on
Anyone with workflowsRemoved nodes, AI Agent version 1, changed node behaviourReplace nodes before upgrading
Slack usersThe Slack API credential requires a signing secretAdd it from the Slack app Basic Information page
Custom node authorsdefaults.color removed; n8n-node dev needs Docker or PodmanUpdate icons and your dev setup
Users of retired featuresChat Hub off by default; import from URL and the Ask AI tab removedTurn Chat Hub back on, or replace it

npm and npx: why n8n drops npm installs

The page is direct: "n8n 3.0 no longer supports installations run using npm or npx n8n." It also says 3.0 "doesn't publish a runnable n8n package to npm", so npm update -g n8n cannot reach it. The suggested routes are the one-line setup, or Docker Compose with Postgres for team or production use. Existing Docker Compose setups do not need to change.

The reason was given in a community post on 10 June 2026: n8n's AI assistant needs a sandbox, and "that sandbox needs to be deployed in a separate Docker container". The one-line setup page says an existing npm install "keeps working for now".

Self-hosted Docker: new defaults and removed variables

In the Docker image, ~/.n8n is /home/node/.n8n. Each row below is from the breaking-changes page.

SettingChange in 3.0To keep the old behaviour
Binary data folder~/.n8n/binaryData is renamed to ~/.n8n/storage on first start. N8N_MIGRATE_FS_STORAGE_PATH is removedMove a binaryData volume mount to storage, or set N8N_STORAGE_PATH to the old path. n8n refuses to start if both folders exist
Binary data modeN8N_DEFAULT_BINARY_DATA_MODE=default is invalid and switches to filesystemSet the mode you want explicitly
Unverified community nodesN8N_UNVERIFIED_PACKAGES_ENABLED defaults to false (was true)Set it to true
Code node task timeoutN8N_RUNNERS_TASK_TIMEOUT defaults to 60 seconds (was 300)Set it explicitly
Compression node limitsMax decompressed size drops from 2 GiB to 256 MiB, max zip entries from 5,000 to 1,000Set the two N8N_COMPRESSION_NODE_MAX variables to 2147483648 and 5000
SSRF protectionThe default blocklist adds ::/128, 100.64.0.0/10, 2002::/16 and 64:ff9b::/96Allow hosts with N8N_SSRF_ALLOWED_IP_RANGES or N8N_SSRF_ALLOWED_HOSTNAMES. Keep default in the blocked list
Encryption key rotationOn by default. Existing data stays readable and is re-encrypted on updateFrom 2.40.3 you can turn it off again
Queue modeManual executions always run on workers. OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS is removedRemove the variable and review worker memory
Removed variablesN8N_DB_PING_TIMEOUT and N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTIONUse DB_PING_TIMEOUT_MS. Move alerting into the hook
Chat HubOff by default in 3.0, removed in 4.0Add chat-hub to N8N_ENABLED_MODULES, for example agents,chat-hub

Removed nodes and their replacements

These are changes to n8n itself, not to how it is installed. Replace each node before upgrading; every replacement already exists in 2.x.

Removed in 3.0Use instead
Function, Function ItemCode node, in all items or each item mode
Item ListsSplit Out, Aggregate, Sort, Limit, Remove Duplicates or Summarize
Cron, IntervalSchedule Trigger
HTML ExtractHTML node, Extract HTML Content operation
Read Binary File(s), Write Binary FileRead/Write Files from Disk
Read PDF, Convert to/from binary dataExtract from File or Convert to File
iCalendarConvert to File, Convert to ICS operation
Workflow Triggern8n Trigger
OpenAI (legacy), OpenAI Assistant, OpenAI ModelOpenAI node (Assistant resource) and OpenAI Chat Model
HTTP Request Tool (legacy)An HTTP Request node on the AI Agent Tool input
Manual Chat Trigger, Chat Messages RetrieverChat Trigger; Chat Memory Manager
Binary, JSON and GitHub document loadersDefault Data Loader
Insert and Load vector store nodes (In Memory, Pinecone, Supabase, Zep)The single vector store node for that store
AI TransformConverted to Code nodes automatically. No new ones can be added
LangChain Code, Motorhead, Zep, Zep Vector Store, SerpApi, OrbitNo direct replacement. For SerpApi use HTTP Request or a verified community node

Our n8n tutorial for beginners uses the Code node modes that replace Function nodes, and the cron expression guide covers the Schedule Trigger that replaces Cron and Interval.

Other workflow changes

  • AI Agent version 1 goes, with its SQL Agent, Conversational, OpenAI Functions, Plan and Execute and ReAct modes. Use the Tools Agent; for SQL jobs, give the agent a Postgres or MySQL tool (see our database automation guide).
  • $getPairedItem is removed. Use $("<node>").item, .itemMatching() or .pairedItem().
  • Execute Sub-workflow versions 1.1 and older lose the Local File and URL sources. Use Database or Define Below.
  • Always Output Data on multi-output nodes such as If and Switch adds an empty item only when every output is empty.
  • $evaluateExpression() leaves the Code node in insecure task runner mode only.
  • Gmail Trigger versions 1 to 1.3 run as 1.4: Max Emails per Poll defaults to 10 (up to 50), drafts are skipped unless Include Drafts is on, and sent and scheduled emails no longer trigger workflows.
  • Webflow OAuth2: the Legacy toggle defaults to off. Reconnect the credential, and turn Legacy on if you still use the v1 Data API.
  • Chat Trigger WebSocket frames become JSON objects with a type field. Update an embedded @n8n/chat to 1.31.0 or later.
  • Retired: import from URL in the editor, the Code node's Ask AI tab, and the "Enable external secrets for project roles" setting.

Two more are worth checking even though the breaking-changes page did not list them on 13 October 2026. The Migration Report's 3.0 rule set in 2.43.4 includes a check for the Execute Sub-workflow node's Run once for each item mode. And the release notes describe the Any workflow caller policy as deprecated "ahead of removal in n8n v3": replace it with a named list of workflows, and stop setting N8N_WORKFLOW_CALLER_POLICY_DEFAULT_OPTION to any.

Custom node authors

  • Remove defaults.color. It only tinted Font Awesome icons; use an SVG or PNG file icon.
  • n8n-node dev now runs the official image in Docker or Podman. Use --external-n8n with your own instance started with N8N_DEV_RELOAD=true, or pin a version with --n8n-image.
  • Test data moves to a per-image n8n-node-cli-data-<image> volume, so export workflows first. --custom-user-folder works only with --external-n8n.
  • n8n-node build, lint, release and npm create @n8n/node are unchanged. See our custom nodes guide.

Before you upgrade: checklist

Everything here can be done today on 2.x. None of it needs 3.0 to exist.

Before any 3.0 upgrade
  • Updated to the newest 2.x stable, so the Migration Report has its latest checks
  • Settings, Migration Report: every Critical issue fixed, in both tabs
  • Startup log read for deprecation warnings (docker compose logs n8n)
  • The .n8n folder backed up: its config file holds the credential encryption key
  • Postgres dumped, plus any S3 or Azure storage and custom node folders
  • A copy of the encryption key kept somewhere off the server
  • Image pinned to an exact version number, not stable, latest or next
  • Database is SQLite or PostgreSQL 16, 17 or 18
  • The backup restored into a separate Compose project and tested there

The Migration Report is for global admins only and rates each issue Critical, Medium or Low. On pinning: n8n's 2.0 notes recommend a specific version number and say the latest and next tags "will be removed in a future major version". A Compose file that tracks stable moves to 3.0 on a routine pull once 3.0 becomes the stable release. The backup guide has the full list of what to copy, and the database page has the supported Postgres versions.

On testing: n8n's update guide suggests its Environments feature, which is a paid one. On the Community Edition, restoring your backup into a second Compose project does the same job.

How to upgrade n8n to 3.0 with Docker Compose

Do this once 3.0 is a stable release and your test copy works. It follows n8n's Docker update steps and the Compose file in our Docker Compose setup guide, where the image tag comes from N8N_VERSION in .env.

The upgrade in five steps
  1. 1
    Stop n8n and back up

    Dump Postgres and archive the .n8n volume.

  2. 2
    Apply the config changes

    Only the values from the table above that you rely on.

  3. 3
    Set the exact 3.x version

    In .env, and the same tag on any runners image.

  4. 4
    Pull, recreate and watch the log

    n8n migrates the database on first start.

  5. 5
    Check /healthz and run key workflows

    Then watch the Executions list for a day.

1. Stop n8n and back up, from the folder with your Compose file:

docker compose stop n8n

# Postgres (-U and -d match POSTGRES_USER and POSTGRES_DB)
docker compose exec -T postgres pg_dump -U n8n -d n8n > n8n-before-3.sql

# The .n8n volume (check its exact name with: docker volume ls)
docker run --rm -v n8n-compose_n8n_data:/data:ro -v "$PWD":/backup alpine \
  tar czf /backup/n8n-data-before-3.tar.gz -C /data .

2. Apply the changes from the tables above. Only add values you rely on, for example:

  n8n:
    environment:
      - N8N_RUNNERS_TASK_TIMEOUT=300          # keep the 2.x five-minute limit
      - N8N_UNVERIFIED_PACKAGES_ENABLED=true  # keep installing unverified nodes
    volumes:
      - n8n_data:/home/node/.n8n
      # only if you mounted binary data separately (was .../binaryData)
      - binary_data:/home/node/.n8n/storage

3. Set the new version in .env, using the exact 3.x number from n8n's release notes.

4. Pull and recreate the containers, then watch the log while n8n migrates the database:

docker compose pull
docker compose down
docker compose up -d
docker compose logs -f n8n

5. Check /healthz, run your key workflows once and watch the Executions list. A published error workflow will alert you to anything that breaks later.

Installed with the one-line setup? Run curl -fsSL https://get.n8n.io | sh -s -- --upgrade from the directory you installed from. It updates N8N_VERSION and N8N_SANDBOX_VERSION in .env and leaves data and other settings alone. Add --version and a number to pick a specific release.

Migrating from npm or npx to Docker

Switch the runtime first and the version later, so you know which change caused a problem. The Migration Report's Docker check gives the plan in one line: "Move this instance to the official Docker image before updating, reusing your existing database and encryption key."

npm to Docker without changing the version
  1. 01
    Note the version

    n8n --version. Then stop n8n and anything that restarts it.

  2. 02
    Back up ~/.n8n

    It holds the config file with your encryption key and, on SQLite, the database.

  3. 03
    Install Docker

    With the docker compose v2 plugin. On Windows, n8n says to use WSL.

  4. 04
    Run the same version

    Mount a copy of the folder at /home/node/.n8n.

  5. 05
    Verify, then remove npm

    Credentials open, workflows run. Two copies must never run at once.

services:
  n8n:
    image: n8nio/n8n:2.43.4   # the version n8n --version printed
    restart: always
    ports:
      - "5678:5678"
    environment:
      - GENERIC_TIMEZONE=Europe/Berlin
      - TZ=Europe/Berlin
    volumes:
      - ./n8n-data:/home/node/.n8n   # a copy of your ~/.n8n folder

Pass the same database variables you used before, and N8N_ENCRYPTION_KEY if you had set one. Without the original key, saved credentials cannot be decrypted. For HTTPS and Postgres, see our n8n self-hosting guide.

What changes on n8n Cloud

The breaking-changes page does not mention Cloud, and n8n has not said when Cloud workspaces move to 3.0. The Docker requirement concerns self-hosted installs; the node removals and behaviour changes are part of n8n itself, so treat them as yours to fix.

Owners control updates in the Cloud dashboard under Manage, then Workspace, in the Updates & maintenance section: the version, a Beta or Stable release track, the update cadence and a maintenance window. n8n recommends the Stable track for mission-critical workloads, and applies security and stability updates automatically whatever you choose (Cloud update docs).

How to roll back a failed upgrade

Restore the backup. n8n has not published a 3.0 rollback procedure, and its backup guide says only that it "recommends taking a full backup before updating".

  1. Stop n8n.
  2. Restore the .n8n folder, any custom node folders and the Postgres database.
  3. Restore your environment variables, including N8N_ENCRYPTION_KEY if you set one.
  4. Set the image back to your old 2.x tag and start n8n.

Anything created since the backup is lost. Do not start 2.x against a database that 3.0 has already migrated: in the 3.0 page's words, "n8n only migrates a database forward".

Next steps

Running n8n in production means planning upgrades like this one. If the upgrade has you weighing Cloud against your own server, our n8n pricing guide and self-hosted limitations set out the trade. If you would rather build your own AI product than maintain workflows, AI SaaS Builder is our program on building one on Supabase, Next.js and the Claude API.

n8n 3.0: FAQ

When is n8n 3.0 released?

n8n's breaking-changes page opens with "n8n 3.0 has been released", but on 13 October 2026 there was no 3.x release on GitHub, npm or Docker Hub. The newest stable release was 2.43.4 and the beta was 2.44.0. n8n's own v3 guide says about October 2026. Release candidate images such as v3-rc-20261012.1 exist for testing only.

Can I still install n8n with npm after 3.0?

No. The breaking-changes page says n8n 3.0 no longer supports installations run using npm or npx n8n, and that 3.0 does not publish a runnable n8n package to npm. An existing npm install keeps running on 2.x. Move it to the official Docker image on your current version first, then upgrade.

Will my workflows break in n8n 3.0?

Only the parts that use something 3.0 removes or changes: older nodes such as Function, Item Lists and Cron, version 1 of the AI Agent node, the $getPairedItem helper, Gmail Trigger versions below 1.4, or Code node tasks longer than the new 60 second default. Settings, then Migration Report, on a recent 2.x version lists what affects your instance.

Does n8n 3.0 affect n8n Cloud?

The breaking-changes page does not mention Cloud. The Docker requirement is about self-hosted installs, but removed nodes and changed node behaviour are changes to n8n itself. Cloud owners control the version, release track and maintenance window under Manage, Workspace, Updates and maintenance, so fix what the Migration Report lists before the workspace moves.

How do I roll back a failed n8n 3.0 upgrade?

Stop n8n, restore the .n8n folder and the database from the backup you took before upgrading, set the image back to your old 2.x version and start it. Do not start 2.x against a database that 3.0 has already migrated: n8n migrates a database forward only, and 3.0 renames the binary data folder on first start.

Will n8n 2.x still get updates after 3.0?

n8n has not said. The breaking-changes page and the v3 guide give no support period for 2.x. For reference, n8n was still publishing 1.x patch releases in October 2026: 1.123.84 came out on 8 October. Check the release notes when 3.0 is published.

What is the n8n Migration Report?

A built-in scan under Settings, then Migration Report, visible to global admins only. It has two tabs: Workflow Issues, which lists affected workflows and nodes, and Instance Issues, which lists settings and environment variables. Each issue is rated Critical, Medium or Low. n8n added it for the 2.0 upgrade and the 3.0 page tells you to open it before upgrading.

Free · no card needed

Start with the free Starter Kit.

A unit economics calculator from AI SaaS Builder, plus four more working files.

Starter Kit5 files · free
See All Access: $99/mo →30-day money-back guarantee