How to Update n8n: The Complete Guide for Self-Hosted and Cloud

Your n8n instance is running a version from three months ago. Every day you delay updating, you accumulate technical debt, miss security patches, and risk a painful multi-version jump that breaks everything.

This isn’t hypothetical. Users in the n8n community regularly report workflows breaking after large version jumps, credentials failing to decrypt, and performance degrading because they skipped too many updates. One user recently described 60+ second execution times after an update that should have taken seconds.

The good news: updating n8n correctly isn’t complicated. But doing it wrong can take your automation infrastructure offline.

The Hidden Cost of Delayed Updates

Every n8n release includes bug fixes, security patches, and feature improvements. When you skip updates, you’re not just missing features. You’re accumulating breaking changes that stack on top of each other.

Jump from version 1.50 to 2.0? You’ll need to handle every breaking change from every version in between, all at once. That’s a recipe for failed workflows, broken credentials, and hours of debugging.

n8n Cloud enforces this by automatically updating instances that haven’t been updated in 120 days. If you ignore the warning emails, your instance gets updated whether you’re ready or not.

Self-Hosted vs Cloud: Different Paths

If you’re on n8n Cloud, updates are managed through the admin dashboard. You get version control, staging environments, and automatic update notifications.

If you’re self-hosting with Docker or npm, you control the entire process. More power, but more responsibility. One wrong configuration and your instance won’t start.

This guide covers both approaches in detail, plus the critical n8n 2.0 migration that affects everyone.

What You’ll Learn

• Pre-update checklist to prevent disasters
• Step-by-step Docker Compose update process
• Cloud version management and controls
• n8n 2.0 migration requirements and breaking changes
• Rollback strategies when updates fail
• Troubleshooting common update problems
• Automated update workflows for hands-off maintenance

Before You Update: The Pre-Update Checklist

Skipping this section is how people break their n8n instances. Every experienced n8n administrator has learned these lessons the hard way.

Critical Pre-Update Steps

Before running any update command, work through this checklist:

1. Check the release notes

Visit the official n8n release notes and read every version between your current version and your target. Look specifically for:

• Breaking changes (labeled clearly in release notes)
• Deprecated features being removed
• Database schema changes
• Node version updates

2. Know your current version

Check your current n8n version before planning any update. In the n8n UI, go to Settings > About or run:

# Docker
docker exec n8n n8n --version

# npm installation
n8n --version

3. Verify your database type

This is critical for the n8n 2.0 update. MySQL and MariaDB are no longer supported in n8n 2.0. If you’re using either database, you must migrate to PostgreSQL before updating.

Check your DB_TYPE environment variable:

# Docker
docker exec n8n printenv | grep DB_TYPE

# Direct check
echo $DB_TYPE

4. Run the Migration Report tool

Starting with version 1.121.0, n8n includes a built-in migration report. Navigate to Settings > Migration Report to see workflow-level and instance-level issues you need to address before upgrading.

This tool shows you exactly what will break. Use it.

5. Export your workflows

Always have a backup. Export all workflows from the n8n UI or use the CLI:

n8n export:workflow --all --output=./workflow-backup/

6. Document your encryption key

The N8N_ENCRYPTION_KEY encrypts all credentials in your database. If you lose this key or use a different one after updating, all credentials become unreadable. Document this value somewhere secure before any update.

What to Back Up Before Updating

Component	Location	Backup Command
PostgreSQL Database	Your database server	pg_dump -U n8n n8n > n8n_backup.sql
SQLite Database	~/.n8n/database.sqlite	cp ~/.n8n/database.sqlite ./backup/
Docker Volumes	/var/lib/docker/volumes/	docker run --rm -v n8n_data:/data -v $(pwd):/backup alpine tar cvf /backup/n8n_data.tar /data
Environment Variables	.env file or Docker config	Copy your .env file to backup location
Encryption Key	N8N_ENCRYPTION_KEY env var	Store securely in password manager

For detailed backup strategies, see our n8n self-hosting mistakes guide which covers data persistence in depth.

Updating Self-Hosted n8n with Docker

Docker is the most common way to self-host n8n, and the update process is straightforward when done correctly.

Docker Compose Update Process

If you’re using Docker Compose (recommended for production), the update process takes four commands:

# 1. Pull the latest n8n image
docker compose pull

# 2. Stop the current stack (keeps volumes intact)
docker compose down

# 3. Start the updated stack
docker compose up -d

# 4. Verify the update succeeded
docker compose logs -f n8n

Your data persists because Docker volumes survive container restarts. As long as your docker-compose.yml mounts volumes correctly, your workflows, credentials, and execution history remain intact.

Important: Your n8n instance will be temporarily offline during steps 2 and 3. Running workflows will stop. Plan updates during maintenance windows if you have workflows that run continuously.

Updating to a Specific Version

Using latest in production is risky. A breaking change could deploy automatically and take down your workflows.

Instead, pin to specific versions in your docker-compose.yml:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:2.0.1
    # ... rest of configuration

To update to a specific version:

1. Check n8n releases on GitHub for available versions
2. Update the version tag in docker-compose.yml
3. Run the standard update commands

Version pinning strategies:

Strategy	Example	Use Case
Exact version	n8n:2.0.1	Production systems requiring stability
Minor version	n8n:2.0	Balance of updates and stability
Latest	n8n:latest	Development/testing only

Complete Docker Compose Example with Version Pinning

Here’s a production-ready docker-compose.yml with proper version pinning:

version: '3.8'

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:2.0.1
    restart: always
    ports:
      - "5678:5678"
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_HOST=${N8N_HOST}
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://${N8N_HOST}/
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      - postgres

  postgres:
    image: postgres:15
    restart: always
    environment:
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  n8n_data:
  postgres_data:

For a complete Docker setup guide, see our n8n Docker setup tutorial.

npm/npx Update Process

If you installed n8n globally via npm:

# Update to latest version
npm update -g n8n

# Or install a specific version
npm install -g [email protected]

# Verify the update
n8n --version

For one-off runs without global installation:

npx n8n@latest

Post-Update Verification

After every update, verify your instance is working correctly:

1. Check the version in Settings > About
2. Test critical workflows by running them manually
3. Verify credentials by testing a connection in each credential
4. Check execution logs for any new errors
5. Monitor performance for the first hour

If anything fails, you’ll need to roll back. We cover rollback strategies later in this guide.

Updating n8n Cloud

Cloud updates are simpler than self-hosted because n8n manages the infrastructure. But you still need to update thoughtfully.

How Cloud Updates Work

n8n Cloud has built-in version management with guardrails:

• Automatic updates occur if you don’t update for 120 days
• Warning emails are sent before forced updates
• Manual updates are available anytime through the admin panel
• Version selection on Pro plans lets you choose specific versions

Manual Cloud Update Process

To update your n8n Cloud instance:

1. Log into your n8n Cloud account
2. Navigate to Admin Settings
3. Find the Version section
4. Review available versions and their release notes
5. Select your target version
6. Click Update

The update applies immediately. Your instance will be briefly unavailable during the update.

Using Environments for Safe Updates

n8n Cloud Pro includes Environments, which let you test updates before applying them to production:

1. Create a staging environment
2. Apply the update to staging first
3. Test your critical workflows
4. If everything works, apply to production

This two-stage approach catches breaking changes before they affect your live workflows.

Cloud vs Self-Hosted Update Comparison

Aspect	n8n Cloud	Self-Hosted
Update trigger	Manual or automatic (120 days)	Manual only
Rollback	Contact support	Full control (version pinning)
Downtime	Brief, managed by n8n	You control timing
Version selection	Available versions only	Any version ever released
Database migration	Handled by n8n	Your responsibility
Testing environment	Environments feature (Pro)	Set up your own staging

n8n 2.0 Migration Guide

n8n 2.0 launched on December 5, 2025. It’s described as a “hardening release” focused on security and stability rather than new features. But it includes breaking changes that require preparation.

What Changed in n8n 2.0

Task runners are now enabled by default. Code node executions run in isolated environments for better security. This is a significant architectural change.

Environment variable access is blocked in Code nodes. The setting N8N_BLOCK_ENV_ACCESS_IN_NODE is now true by default. If your Code nodes access environment variables directly, they’ll fail after updating.

MySQL and MariaDB support removed. You must migrate to PostgreSQL or SQLite before updating to 2.0. There’s no workaround.

Legacy SQLite driver removed. The pooling driver (with WAL mode) is now the only SQLite option. This actually improves performance by up to 10x according to n8n benchmarks.

The —tunnel option removed. If you use n8n --tunnel for development, you’ll need to find an alternative like ngrok or Cloudflare Tunnel.

Database Migration Requirements

If you’re using MySQL or MariaDB, you cannot update to n8n 2.0 until you migrate.

The migration process:

# 1. Export all data from your current database
n8n export:workflow --all --output=./migration-backup/
n8n export:credentials --all --output=./migration-backup/

# 2. Set up PostgreSQL (see our PostgreSQL guide)
# 3. Update your environment variables to point to PostgreSQL
# 4. Start n8n with the new database
# 5. Import your data
n8n import:workflow --input=./migration-backup/
n8n import:credentials --input=./migration-backup/

For detailed PostgreSQL setup, see our n8n PostgreSQL setup guide.

Warning: The export:credentials command exports encrypted credentials. You need the same N8N_ENCRYPTION_KEY to import them into the new database.

Code Node Changes

If your Code nodes access environment variables like this:

// This will FAIL in n8n 2.0
const apiKey = process.env.MY_API_KEY;

You have two options:

Option 1 (Recommended): Use n8n credentials instead

Create a custom credential for your API key and access it properly through the node’s credential system.

Option 2: Re-enable environment access (not recommended)

N8N_BLOCK_ENV_ACCESS_IN_NODE=false

This works but defeats the security improvements. Only use this as a temporary bridge while you migrate to proper credential usage.

Task Runner Configuration

Task runners isolate Code node execution from the main n8n process. This prevents malicious or buggy code from crashing your entire instance.

For most users, the default configuration works fine. But if you run n8n in queue mode with external task runners, you need the separate runner image:

services:
  n8n-runner:
    image: docker.n8n.io/n8nio/n8n-runner
    environment:
      - N8N_RUNNERS_MODE=external
      # ... other configuration

For queue mode configuration, see our n8n queue mode guide.

v1.x vs v2.0 Breaking Changes Summary

Change	v1.x Behavior	v2.0 Behavior	Action Required
Task runners	Disabled by default	Enabled by default	None (automatic)
Env access in Code	Allowed	Blocked by default	Migrate to credentials
MySQL/MariaDB	Supported	Not supported	Migrate to PostgreSQL
SQLite driver	Legacy available	Pooling only	None (automatic)
—tunnel option	Available	Removed	Use ngrok/Cloudflare

v1.x Support Timeline

n8n will continue supporting version 1.x for 3 months after the 2.0 release (until approximately March 2025). During this period, v1.x receives security and bug fixes only.

There’s no rush to update immediately. Use this time to:

1. Run the Migration Report tool
2. Migrate from MySQL/MariaDB if needed
3. Update Code nodes that access environment variables
4. Test the update in a staging environment

Rollback Strategies

Updates don’t always go smoothly. Having a tested rollback plan prevents extended downtime.

When Updates Go Wrong

Common post-update problems that require rollback:

• Workflows fail silently without clear error messages
• Credentials stop working due to encryption key issues
• Performance degrades significantly (one user reported 60+ second execution times)
• Nodes behave differently than expected
• UI becomes unresponsive or crashes

If you encounter any of these, don’t panic. Rollback is straightforward if you prepared correctly.

Docker Rollback Process

Rolling back a Docker deployment is simple because you control the image version:

# 1. Stop the current (broken) version
docker compose down

# 2. Edit docker-compose.yml to use the previous version
# Change: image: docker.n8n.io/n8nio/n8n:2.0.1
# To:     image: docker.n8n.io/n8nio/n8n:1.70.3

# 3. Pull the previous version
docker compose pull

# 4. Start the previous version
docker compose up -d

# 5. Verify the rollback worked
docker compose logs -f n8n

Your data should remain intact because it’s stored in volumes, not the container.

Database Rollback Considerations

Here’s the catch: database schema changes may not be reversible.

When n8n updates, it often runs migrations that change the database structure. These migrations are designed to go forward, not backward.

If you downgrade the n8n application but keep the upgraded database, you might encounter:

• n8n refusing to start due to schema mismatch
• Missing columns or tables causing errors
• Corrupted data relationships

Best practices for database safety:

1. Always back up your database before updating
2. Test updates in a staging environment first
3. If you must restore, restore both the application and database together
4. Keep backups for at least 30 days

Emergency Recovery Checklist

If an update goes wrong and you need to recover:

1. Don’t panic. Most issues are recoverable.
2. Check the logs first: docker compose logs n8n
3. Verify the database is running and accessible
4. Check the encryption key matches what was used before
5. Try a clean restart before rolling back: docker compose down && docker compose up -d
6. Roll back the application if restart doesn’t work
7. Restore database from backup as a last resort
8. Document what happened for future reference

If you’re stuck, our n8n consulting services include emergency support for critical failures.

Troubleshooting Update Problems

These are real problems from the n8n community, with real solutions.

Problem: Workflows Stopped Working After Update

Symptoms: Workflows that worked before now fail with errors, or complete but produce wrong results.

Common causes:

1. Node syntax changes. n8n occasionally updates expression syntax. For example, the 1.78.0 update changed $items('NodeName') to $('NodeName').all().

2. Node version incompatibility. Some workflows reference specific node versions that behave differently in newer versions.

3. Deprecated nodes removed. Nodes marked as deprecated eventually get removed.

Solutions:

• Check the release notes for syntax changes affecting your nodes
• Update deprecated syntax in your Code nodes
• Use the workflow debugger to identify which node is failing
• Re-add removed nodes from the node panel (sometimes they’re just hidden)

Problem: Credentials No Longer Work

Symptoms: All credentials show “Authentication failed” or “Could not decrypt.”

Cause: The N8N_ENCRYPTION_KEY doesn’t match what was used to encrypt the credentials.

This happens when:

• You forgot to set the encryption key after updating
• The key was regenerated accidentally
• You’re running multiple instances with different keys

Solutions:

# Check if the key is set
docker exec n8n printenv | grep N8N_ENCRYPTION_KEY

# Compare with your documented key
# If different, update your docker-compose.yml or .env file

If the key is lost, you’ll need to re-create all credentials manually. There’s no way to decrypt credentials without the original key.

For credential management best practices, see our n8n credential management guide.

Problem: Performance Degradation After Update

Symptoms: Workflows that completed in seconds now take minutes. The UI is sluggish.

Causes:

1. Task runner overhead. In n8n 2.0, task runners add isolation but also add some overhead.
2. Database connection issues. The update might have changed connection pooling behavior.
3. Memory pressure. New versions sometimes have different memory requirements.

Solutions:

• Check container resource limits: docker stats n8n
• Increase memory allocation if constrained
• Review task runner configuration
• Check database query performance
• Consider enabling queue mode for heavy workloads

For timeout-related issues, see our n8n timeout troubleshooting guide.

Problem: Node Version Stuck

Symptoms: A node (like the AI Agent) shows an older version even after updating n8n.

Cause: Node versions are pinned in workflows and don’t auto-update.

Solutions:

1. Delete the old node from your workflow
2. Add a fresh copy from the node panel
3. Reconfigure the node settings
4. Save and test the workflow

For community nodes, check if updated versions are available on npm.

Problem: Authentication Errors After Update

Symptoms: Can’t log into n8n, or OAuth connections fail.

Solutions:

• Clear browser cache and cookies
• Check if N8N_HOST and WEBHOOK_URL are configured correctly
• Verify OAuth redirect URLs match your domain
• Review the authentication errors guide

Automated Update Strategies

Manually updating is fine for occasional updates. But if you want hands-off maintenance, automation helps.

Watchtower for Automatic Docker Updates

Watchtower monitors Docker containers and automatically updates them when new images are available.

Add Watchtower to your docker-compose.yml:

services:
  watchtower:
    image: containrrr/watchtower
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 86400 --cleanup n8n
    environment:
      - WATCHTOWER_NOTIFICATIONS=email
      - [email protected]
      - [email protected]

This configuration:

• Checks for updates every 24 hours (86400 seconds)
• Only updates the n8n container
• Cleans up old images to save disk space
• Sends email notifications when updates occur

n8n Workflow for Version Monitoring

Build a workflow that checks for new n8n versions and notifies you:

1. Schedule Trigger running daily
2. HTTP Request to check GitHub releases API
3. Compare current version vs latest release
4. Send notification via Slack, email, or Telegram if new version available

Templates for this exist in the n8n workflow library.

When NOT to Auto-Update

Automatic updates are convenient but risky for:

• Production-critical workflows that can’t tolerate any downtime
• Major version changes (like 1.x to 2.0) that include breaking changes
• Custom node deployments that might break with core updates
• Regulated environments that require change control processes

For these cases, stick with manual updates after testing in staging.

Update Schedule Best Practices

Having a consistent update schedule prevents the dangerous situation of falling too far behind.

Recommended Update Frequency

Update Type	Frequency	Reason
Patch versions (x.x.1 → x.x.2)	Within 1-2 weeks	Security fixes, bug patches
Minor versions (x.1.x → x.2.x)	Monthly	New features, improvements
Major versions (1.x → 2.x)	After testing	Breaking changes, requires preparation

Version Pinning Strategy

Never use latest in production. Here’s why:

# DANGEROUS: Could deploy breaking changes automatically
image: docker.n8n.io/n8nio/n8n:latest

# SAFE: Explicit version control
image: docker.n8n.io/n8nio/n8n:2.0.1

Update the version in your configuration file deliberately, after reviewing release notes and testing.

Change Management Process

For teams with multiple people or compliance requirements:

1. Monitor releases via GitHub notifications or RSS
2. Review release notes for breaking changes
3. Test in staging environment with production data copy
4. Schedule maintenance window (if needed)
5. Update production during low-traffic period
6. Monitor for issues in the first hour
7. Document the update in your change log

For help implementing proper update processes, our n8n support packages include update management.

Frequently Asked Questions

Can I skip versions when updating n8n?

Yes, but carefully. You can update from any version to any newer version directly. However, you must handle all breaking changes from every version you’re skipping.

For example, updating from 1.50 to 2.0 means addressing breaking changes from 1.51, 1.52, …, 1.121, and 2.0. The more versions you skip, the more potential issues.

Best practice: Keep updates small and frequent. Updating monthly means handling only 2-4 versions of changes at a time.

What happens if I don’t update my n8n Cloud instance?

n8n Cloud sends warning emails when your instance hasn’t been updated for a while. If you ignore these for 120 days, n8n will automatically update your instance.

This forced update happens to ensure you have security patches. But it could include breaking changes you’re not prepared for. Better to update proactively on your own schedule.

How do I update n8n without losing my workflows?

Your workflows are stored in the database, not the n8n application. As long as your database persists:

• Docker: Volumes keep your data safe. Just update the container.
• npm: Your ~/.n8n directory contains your SQLite database. Don’t delete it.
• Cloud: n8n manages your data. Updates don’t affect it.

Always back up before updating, but normal updates shouldn’t touch your data.

Should I update to n8n 2.0 immediately?

Not necessarily. n8n 2.0 includes breaking changes that require preparation:

1. MySQL/MariaDB users must migrate to PostgreSQL first
2. Code nodes accessing environment variables need updates
3. Some deprecated features are removed

Take time to:

• Run the Migration Report tool
• Test in a staging environment
• Read the v2.0 breaking changes documentation

Version 1.x will continue receiving security updates for 3 months after the 2.0 release.

How do I check what version of n8n I’m running?

UI method: Log into n8n, click your profile icon, and select Settings > About.

CLI method:

# Docker
docker exec n8n n8n --version

# npm installation
n8n --version

API method:

curl -s http://localhost:5678/api/v1/info | jq '.n8nVersion'

---

Keeping n8n updated is essential for security, performance, and access to new features. With proper preparation, backup strategies, and testing, updates become routine maintenance rather than stressful events.

If you need help with complex migrations or want ongoing support for your n8n infrastructure, our n8n self-hosted setup service and consulting packages are designed for exactly these situations.