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

Checked against n8n's v3.0 breaking-changes page, documentation, GitHub repository, npm and Docker Hub on October 1, 2026. n8n says it will update that page "as n8n 3.0 approaches its release", so check it again before you upgrade.

n8n 3.0 isn't out yet. n8n's breaking-changes page says it is "scheduled for October 2026", and on October 1, 2026 the newest stable release was 2.41.4, with no 3.x version on GitHub, npm or Docker Hub. The change most people must act on: self-hosted 3.0 runs only from the official Docker image, so npm and npx installs have to move to Docker first. 3.0 also removes 36 older nodes, drops version 1 of the AI Agent node, renames the binary data folder and tightens several defaults. A 2.x instance already lists what affects you under Settings > Migration Report.

n8n 3.0 release date: is it out yet?

Not as of October 1, 2026, and n8n hasn't named a day. Its v3 guide on GitHub (DEVELOPING_V3.md) says "~October 2026" and calls 3.0 "an operational release: breaking changes, removals, and legacy cleanup — not a big-bang feature launch."

Sources: GitHub releases, n8n's Docker page, npm and Docker Hub. n8n's guide offers the v3 images for trials before release and adds: "Do not use them in production." To test one, pin a fixed tag such as v3-rc-20260928.1; v3-rc and v3-nightly move. n8n also hasn't said how long 2.x will get fixes after 3.0; for 2.0, its announcement promised 1.x three months of bug and security fixes.

n8n 3.0 breaking changes by who they affect

npm and npx: why n8n drops npm installs

The page is direct: "n8n 3.0 will no longer support installations run using npm or npx n8n." 3.0 also "doesn't publish a runnable n8n package to npm", so npm update -g n8n can't reach it. n8n's one-line setup page says an existing npm install "keeps working for now" and that a migration guide "is coming soon". A June 2026 community post gave the reason: n8n Assistant runs code in a sandbox that needs its own Docker container.

Self-hosted Docker: new defaults and removed variables

In the Docker image, ~/.n8n is /home/node/.n8n.

Three security changes are listed with no details yet: "Tighter handling of risky resource names", "More secure credential behavior" and "Key rotation enabled by default". Re-read them before upgrading.

Removed nodes and their replacements

These are changes to n8n itself, so they apply on n8n Cloud too. Replace each node before upgrading:

Full wording: removed nodes. Our n8n beginner's tutorial uses the Code node modes that replace Function nodes.

Other workflow changes

• AI Agent version 1 goes, with its SQL, Conversational, OpenAI Functions, Plan and Execute and ReAct modes. Update to the latest version (Tools Agent workflows behave the same); for SQL Agent jobs, give the agent a Postgres or MySQL tool (see our database automation guide).
• $getPairedItem is removed: use pairedItem or $("<node-name>").item.
• Execute Sub-workflow versions 1.1 and older lose the Local File and URL sources: use Database or Define Below.
• Always Output Data on If and Switch adds an empty item only when every output is empty.
• $evaluateExpression() leaves the Code node; only N8N_RUNNERS_INSECURE_MODE=true setups are affected.
• Gmail Trigger versions 1 to 1.3 run as 1.4: drafts are skipped unless Include Drafts is on, scheduled emails and sent emails outside the inbox no longer trigger, and Max Emails per Poll (default 10, up to 50) applies to every poll.
• Webflow OAuth2 requests v2 scopes on reconnect; turn on Legacy first if you use the v1 Data API.
• Chat Trigger WebSocket messages become JSON frames; update an embedded @n8n/chat to 1.31.0 or later, or parse JSON in a custom client.
• Retired: import from URL in the editor, the Code node's Ask AI tab, and the Enterprise setting "Enable external secrets for project roles".

Also flagged by the Migration Report

n8n 2.41.4's report runs two 3.0 checks that weren't on the breaking-changes page on October 1, 2026 (rule source). The Execute Sub-workflow node's Run once for each item mode "is being removed": put a Loop Over Items node before it and use Run once with all items. The Any workflow caller policy, "deprecated ahead of removal in n8n v3" per the 2.37 release notes, needs replacing with Selected workflows or the same-project option, and N8N_WORKFLOW_CALLER_POLICY_DEFAULT_OPTION should no longer be any.

Custom node authors

• Remove defaults.color. Font Awesome icons now show in a neutral color, so 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 one with --n8n-image docker.n8n.io/n8nio/n8n:<n8n-version>.
• Test data moves to an n8n-node-cli-data-<image> volume and doesn't carry over from ~/.n8n-node-cli/.n8n, so export it first. --custom-user-folder now needs --external-n8n.
• Build, lint, release and npm create @n8n/node are unchanged. Unverified nodes need N8N_UNVERIFIED_PACKAGES_ENABLED=true on 3.0. See our custom nodes guide.

Before you upgrade: checklist

1. Update to the newest 2.x stable and open Settings > Migration Report. In 2.41.4 it checks for 3.0 and lists workflow and instance issues by severity, for global admins (how it works). Checks were added during 2.x (the Execute Sub-workflow source check arrived in 2.34), so older versions show less.
2. Read the startup log (docker compose logs n8n): 2.x logs a deprecation warning for each 3.0 configuration change that affects you.
3. Back up the .n8n folder (its config file holds the credential encryption key; on SQLite it also holds the database), Postgres, any S3 or Azure storage, and N8N_CUSTOM_EXTENSIONS folders. Keep the key off the server too (backup guide).
4. Pin the image version. n8n's 2.0 notes recommend it and say latest and next "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.
5. Test on a copy. The update guide suggests Environments, a paid feature; on the free Community Edition, restore your backup into a separate Compose project and try 3.0 there.
6. Check the database: SQLite or PostgreSQL 16, 17 or 18 (as of July 2026, per the database docs). The 3.0 page lists no database changes; upgrade an older Postgres first, separately.
7. Clear old settings: switch WEBHOOK_URL to N8N_WEBHOOK_URL (deprecated since 2.35.0, per the endpoint docs), and keep any n8nio/runners sidecar on n8n's exact tag (task runner docs).

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 self-hosting guide, where the image is n8nio/n8n:${N8N_VERSION}.

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, and the same tag on any n8nio/runners image:

N8N_VERSION=<the exact 3.x version 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. An 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 edits N8N_VERSION and N8N_SANDBOX_VERSION in .env. Use --version followed by a version number instead to pick a specific release.

Migrating from npm or npx to Docker

n8n's step-by-step guide isn't out yet. The Migration Report's Docker check gives the plan: "Move this instance to the official Docker image before updating, reusing your existing database and encryption key." Switch the runtime first and the version later, so you know which change caused a problem.

1. Note your version with n8n --version, then stop n8n, including any process manager that restarts it.
2. Back up ~/.n8n, which holds the config file with your encryption key and, on SQLite, the database. Back up Postgres too if you use it.
3. Install Docker with Compose v2. On Windows, n8n's Compose guide says to use WSL and keep the project in the WSL filesystem, not under /mnt/c, so copy the folder there.
4. Run the same version on a copy of the folder mounted at /home/node/.n8n (image README). The image runs as the node user (Dockerfile), which must be able to write to it. Pass the same database variables, and N8N_ENCRYPTION_KEY if you set one.

services:
  n8n:
    image: n8nio/n8n:2.41.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

5. Run docker compose up -d, sign in, and check that credentials work and workflows run. Then remove the npm install so two copies never run at once.
6. Upgrade to 3.0 later with the steps above. For HTTPS and Postgres, see our self-hosting guide.

What changes on n8n Cloud

The Docker requirement is for self-hosted n8n, so Cloud skips it, but the workflow changes above still apply. The breaking-changes page doesn't say when Cloud moves to 3.0. Owners control updates under Manage > Workspace > Updates & maintenance: the version, a Beta or Stable track (n8n recommends Stable for mission-critical workloads), the update cadence and a maintenance window. Security and stability updates always apply automatically (Cloud update docs). In 2.41.4's editor code, the Migration Report is gated by user permission, not hosting type, so it isn't limited to self-hosted instances.

How to roll back a failed upgrade

n8n hasn't published a 3.0 rollback procedure. What it does document:

• Restore the backup. The backup guide lists rolling back a failed update as a reason to back up. Stop n8n, restore the .n8n folder, custom node folders, Postgres and your environment variables, set the image to your old 2.x tag and start it. Anything created since the backup is lost.
• Don't start 2.x on a migrated database. As the 3.0 page puts it, n8n "only migrates a database forward", and 3.0 renames the binary data folder on first start.
• n8n db:revert, in n8n's npm docs, undoes one database migration per run, so the backup is simpler for a major version.

Next steps

Running n8n in production means planning upgrades like this one. See our guides to self-hosting n8n, error handling and custom nodes. If you would rather build your own AI product than maintain workflows for clients, AI SaaS Builder covers building one on Supabase, Next.js and the Claude API, deploying it on Vercel, and charging with Stripe.

n8n 3.0 FAQ