n8n 3.0 upgrade checklist for self-hosted n8n
One page, no sign-up. Print it, or choose Save as PDF in the print dialog. The full guide explains each step.
- October 27, 2026
- Early December 2026 (planned)
- December 31, 2026
- 12 months after 3.0 stable
Before you upgrade (on 2.x)
- Open Settings > Migration Report. Missing? Update to n8n 2.39 or later first. On 1.x, move to 2.x first.
- Review both tabs, Workflow issues and Instance issues, and fix the workflows they list.
- Function → Code node (Run Once for All Items). Function Item → Code node (Run Once for Each Item).
- Item Lists → Split Out, Aggregate, Sort, Limit, Remove Duplicates or Summarize.
- Cron and Interval → Schedule Trigger.
- Read Binary File(s) and Write Binary File → Read/Write Files from Disk. Read PDF → Extract from File.
- Workflow Trigger → n8n Trigger. Legacy HTTP Request Tool → HTTP Request node on the AI Agent's Tool input.
- AI Agent node v1 and its older modes → Tools Agent.
- Move npm or npx installs to Docker. 3.0 requires Docker. Docker Compose users don't need to switch.
- Slack Trigger workflows: add the signing secret to the Slack API credential before upgrading.
- Take a full backup. There is no direct rollback from 3.x to 2.x.
- Restore the backup onto a staging copy and open a few workflows. Production stays on 2.x until the staging rehearsal runs cleanly.
When you switch to 3.0
- 3.0 renames ~/.n8n/binaryData to ~/.n8n/storage on first start and stops if both exist. Keep a binaryData volume mount on 2.x. On 3.0, mount it at storage or set N8N_STORAGE_PATH.
- N8N_DEFAULT_BINARY_DATA_MODE=default is no longer valid. n8n switches it to filesystem.
- Delete removed variables: OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS, N8N_DB_PING_TIMEOUT (use DB_PING_TIMEOUT_MS), N8N_WORKFLOW_TAGS_DISABLED, N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION.
- N8N_UNVERIFIED_PACKAGES_ENABLED changes from true to false. Set it to true to keep unverified community nodes loading.
- N8N_RUNNERS_TASK_TIMEOUT drops from 300 (5 minutes) to 60 (1 minute). Set it if tasks need longer.
- Chat Hub is off by default. If you use it, add chat-hub to N8N_ENABLED_MODULES.
- Other Slack workflows: add the signing secret the next time you edit the Slack API credential.
- Import from URL is removed from the editor. Compression node defaults drop to 256 MiB decompressed and 1,000 zip entries.
- Rehearse on staging first: upgrade the staging copy to 3.0 with these changes and run the workflows the Migration Report flagged.
- Then production, with the same changes. Keep the pre-upgrade backup until it has run cleanly.