n8n v2 migration guide

The wait is finally over. n8n v2.0 has officially landed, bringing the highly anticipated Autosave, a massive performance boost, and a "Draft vs. Publish" workflow that changes how we build automations forever.

If you are hosting n8n on Zeabur, here’s a full guide that helps you updating your instance is generally, but because v2 brings some architectural changes (especially for Python users), there are three different paths to take depending on how you use Code nodes.

Here is how to migrate your Zeabur project safely.

---

🚀 Just want to start fresh?

If you prefer to start with a clean slate rather than migrating an existing instance, we have released a pre-configured Static n8n v2 Template. It comes optimized for Zeabur out of the box.

Deploy n8n v2 Template on Zeabur →

---

Path 1: The "Basic" User (Standard Upgrade)

Who is this for?

• You use standard n8n nodes (Webhooks, HTTP Requests, Google Sheets, etc.).
• You use JavaScript in your Code nodes.
• You do not use Python in your Code nodes.

If this sounds like you, the upgrade process on Zeabur is incredibly simple.

How to Upgrade:

1. Log in to your Zeabur Dashboard.
2. Click on your n8n service.
3. Navigate to the Settings tab.
4. Find the Image Tag field.
5. Change the tag from your current version (or latest) to 2.1.4 (or the newest version available).
6. Zeabur will automatically redeploy your service.

That’s it. Once the service restarts, you will see the new v2 interface.

⚠️ Important: Even for basic users, v2 has breaking changes regarding how data flows between sub-workflows. We strongly recommend reading the Official Breaking Changes Guide before you switch.

---

Path 2: The "Pyodide" User (Legacy Python Support)

Who is this for?

• You are currently using Python in your workflows.
• You are utilizing the Pyodide implementation (the lightweight, browser/server-side Python that does not require a full external task runner).
• You want to keep your current simple architecture without deploying complex Task Runners.

The Catch: n8n v2 changes how Python is handled. If you simply update the image tag, your Pyodide-based nodes may fail because the environment requirements have changed. You need to apply a specific configuration to your Zeabur instance to maintain this functionality.

How to Upgrade:

We have prepared a specific configuration guide for this scenario. Please verify your settings and environment variables against the guide below to ensure Pyodide continues to function on Zeabur:

👉 Guide: Upgrading n8n v2 with Pyodide on Zeabur

Follow the steps in the link above to patch your current instance before expecting your Python workflows to run successfully.

---

Summary of Breaking Changes

Whether you are a basic or advanced user, these v2 changes affect everyone:

1. Sub-Workflow Data: If you use the "Execute Workflow" node, n8n now returns the actual result of the sub-workflow rather than passing the input data through. Check your data output!
2. Code Node Security: By default, Code nodes can no longer access environment variables (process.env). You must explicitly enable permissions if your code relies on them.
3. Save vs. Publish: You now have a "Draft" state. Clicking "Save" does not make changes live. You must click "Publish" to update your active workflows.

For a deep dive into every technical change, please refer to the official documentation: 📄 n8n v2.0 Breaking Changes Documentation

---

⚡️ Quick Decision Guide

Not sure which path to take? Use this table to decide:

Feature / Usage	Path 1: Basic	Path 2: Pyodide	New Deployment
Primary Code Language	JavaScript only	JavaScript + Simple Python	All
External Pip Packages	No	No (Standard Libs only)	-
Performance Needs	Standard	Standard	Standard
Migration Action	Update Image Tag	Update Tag + Apply Config	Use Template
Best For	Most Users	Lightweight Python Users	New / Clean Start

Final Thought

Upgrading to v2 on Zeabur is a huge step forward for stability and developer experience. Choose the path that fits your workflow complexity, and happy automating! 🚀