n8n 3.0 : le guide de migration (Docker, nœuds supprimés)

Migrer vers n8n 3.0 demande trois choses : une instance sur Docker (npm et npx ne sont plus supportés), des workflows débarrassés des nœuds legacy retirés, et une sauvegarde complète avant une mise à jour qui ne permet aucun retour en arrière. La bêta sort le 27 octobre 2026 et la version stable est prévue pour début décembre 2026, selon l’annonce officielle de n8n publiée le 23 octobre.

Cette version majeure n’apporte pas de nouvelle fonctionnalité visible. n8n la présente comme une release de fiabilité, de stabilité et de sécurité, et c’est précisément ce qui la rend délicate : tout le travail est dans ce qui disparaît.

J’héberge mon instance n8n en Docker et j’ai passé le rapport de migration en revue pour préparer ce guide. Voici la liste complète de ce qui change, puis la procédure dans l’ordre où je vous conseille de la suivre.

n8n 3.0 en bref : dates, périmètre et nature des changements

n8n 3.0 est une version de nettoyage : pas de nouveauté majeure, mais une liste longue de suppressions et de nouveaux réglages par défaut. L’équipe n8n annonce que les prochaines fonctionnalités seront livrées sur la branche 3.x, ce qui rend la migration inévitable à moyen terme.

Élément	Information vérifiée
Bêta 3.0.0	27 octobre 2026, sans inscription (Cloud : « 3.0.0 Beta (early access) »)
Stable 3.x	Début décembre 2026
Dernière 2.x au 26 octobre	2.45 (publiée le 20 octobre 2026)
Support de 2.x	Correctifs de sécurité et bugs critiques pendant 12 mois après la 3.x stable
Fin de support de 1.x	31 décembre 2026 (passage obligatoire par 2.x avant 3.x)
Retour arrière	Impossible : la mise à jour 2.x vers 3.x est à sens unique
Éditions concernées	Self-hosted, Cloud, Business, Enterprise

Le contexte compte. n8n revendique 1,7 million de développeurs et builders actifs chaque mois, plus de 1 400 clients entreprise et une valorisation de 5,2 milliards de dollars depuis l’entrée de SAP au capital, selon le communiqué du 12 mai 2026 relayé par Tech.eu.

Avec cette base installée, l’éditeur ne peut plus traîner indéfiniment des nœuds hérités de 2020. La v3 solde cette dette, et c’est aux utilisateurs self-hosted d’absorber le choc.

Si vous découvrez l’outil, commencez par mon tutoriel complet n8n en français : il part directement sur une installation Docker, ce qui vous évite la première étape de ce guide. La fiche n8n résume les éditions et les tarifs si vous hésitez encore entre self-hosted et Cloud.

Docker obligatoire : la fin des installations npm et npx

À partir de n8n 3.0, une instance self-hosted doit tourner dans un conteneur basé sur l’image officielle. La page des changements incompatibles est sans ambiguïté : « Self-hosted n8n requires a Docker-based deployment », et aucune version 3.x ne sera publiée sur npm.

Qui est concerné, qui ne l’est pas

Trois cas de figure se présentent.

• Vous avez installé n8n avec npm install n8n -g ou vous le lancez avec npx n8n : vous êtes directement concerné. Sans migration vers Docker, vous resterez bloqué en 2.x.
• Vous utilisez Docker, Docker Compose ou un panneau comme Dokploy, Coolify ou l’app Hostinger : rien à changer côté infrastructure. Le reste du guide (nœuds, sécurité, variables) vous concerne en revanche pleinement.
• Vous déployez sur Kubernetes ou via le chart Helm : n8n précise que ces installations ne sont pas affectées, puisqu’elles utilisent déjà l’image Docker.

Le changement touche aussi les développeurs de nœuds communautaires. La commande n8n-node dev exécute désormais l’image officielle dans un conteneur et exige Docker ou Podman. Les workflows et identifiants de test ne sont pas repris : exportez-les avant de mettre à jour l’outillage.

Passer de npm à Docker sans perdre ses workflows

La règle que je vous recommande : migrez l’infrastructure d’abord, en restant en 2.x, et ne touchez à la version majeure qu’ensuite. Deux changements simultanés rendent un incident impossible à diagnostiquer.

Deux éléments doivent survivre au déménagement : votre base de données (SQLite dans ~/.n8n/database.sqlite ou votre Postgres externe) et votre clé de chiffrement N8N_ENCRYPTION_KEY, stockée dans ~/.n8n/config si vous ne l’avez jamais définie explicitement. Sans cette clé, aucun de vos identifiants (credentials) ne sera déchiffrable dans la nouvelle instance.

# 1. Arrêter l'instance npm et récupérer la clé de chiffrement
cat ~/.n8n/config   # noter la valeur de encryptionKey

# 2. Créer le volume Docker et y copier les données existantes
docker volume create n8n_data
docker run --rm -v n8n_data:/data -v ~/.n8n:/from:ro alpine:3 \
  sh -c "cp -a /from/. /data/ && chown -R 1000:1000 /data"

# 3. Lancer la même version 2.x en Docker, en épinglant le tag
docker run -d --name n8n -p 5678:5678 \
  -e N8N_ENCRYPTION_KEY="<votre clé>" \
  -e GENERIC_TIMEZONE="Europe/Paris" -e TZ="Europe/Paris" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n:2.45.0

Pour une machine vierge, n8n propose aussi une installation en une ligne (curl -fsSL https://get.n8n.io | sh) qui déploie Docker Compose et les dépendances. C’est l’option que l’annonce de la v3 suggère aux utilisateurs npm, mais elle convient mieux à un nouveau serveur qu’à une migration de données existantes. La documentation Docker officielle détaille la variante Postgres si vous ne voulez pas rester sur SQLite.

Vérifiez ensuite que vos workflows s’exécutent et que les identifiants s’ouvrent sans erreur de déchiffrement. Tant que ce n’est pas le cas, ne passez pas à la suite.

Les nœuds supprimés dans n8n 3.0 et leurs remplaçants

Une trentaine de types de nœuds disparaissent dans n8n 3.0, et tout workflow qui en contient échouera après la mise à jour. Le guide indépendant de jacar.es, qui a testé l’image nightly le 16 septembre 2026, en dénombre 37 : le catalogue passe de 565 types de nœuds en 2.39.6 à 528 dans la nightly. La bonne nouvelle : la quasi-totalité possède un remplaçant direct, et le Migration Report sait en convertir une partie automatiquement.

Nœud retiré	Remplaçant dans n8n 3.0
Function, Function Item	Code (modes « Run Once for All Items » / « Run Once for Each Item »)
Item Lists	Split Out, Aggregate, Sort, Limit, Remove Duplicates ou Summarize
Cron, Interval	Schedule Trigger
HTML Extract	HTML (opération Extract HTML Content)
Read PDF	Extract from File (Extract From PDF)
Read/Write Binary File(s)	Read/Write Files from Disk
Convert to/from binary data	Convert to File / Extract from File
iCalendar	Convert to File (Convert to ICS)
Workflow Trigger	n8n Trigger
OpenAI (legacy), OpenAI Assistant	Nœud OpenAI (ressource Assistant)
OpenAI Model	OpenAI Chat Model
HTTP Request Tool (legacy)	HTTP Request branché sur l’entrée Tool d’un AI Agent
Manual Chat Trigger	Chat Trigger
Chat Messages Retriever	Chat Memory Manager
Binary / JSON Input Loader, GitHub Document Loader	Default Data Loader
Vector Store Insert / Load	Simple, Pinecone ou Supabase Vector Store
AI Transform	Converti automatiquement en nœud Code (plus ajoutable)
LangChain Code, Motorhead, Zep, Zep Vector Store, SerpApi, Orbit	Aucun remplaçant direct

Deux pièges concrets sur les conversions les plus fréquentes. Pour Function Item vers Code, la variable item devient $json et le retour s’écrit return $input.item. Pour Item Lists, il n’y a pas un remplaçant mais six : il faut relire chaque usage pour choisir entre Split Out (éclater un tableau) et Aggregate (regrouper des items).

Les anciens modes AI Agent et le nœud OpenAI legacy

Si vous avez construit un agent avant 2025, vérifiez sa version. n8n 3.0 supprime la version 1 du nœud AI Agent, c’est-à-dire les modes SQL Agent, Conversational Agent, OpenAI Functions Agent, Plan and Execute et ReAct. Seul le Tools Agent subsiste, et c’est le mode utilisé dans mon guide pour créer un premier agent IA avec n8n.

Le remplacement n’est pas toujours mécanique. Un ReAct Agent branché sur un modèle sans appel d’outils natif n’a pas d’équivalent strict dans le Tools Agent ; il faut changer de modèle ou repenser la boucle. Le HTTP Request Tool legacy disparaît aussi : vous branchez désormais un nœud HTTP Request classique sur l’entrée Tool de l’agent.

Helpers et expressions retirés

Trois fonctions de code disparaissent et ne sont pas signalées par une simple lecture du canevas.

• $getPairedItem : remplacé par $('<nœud>').item, .itemMatching(<index>) ou .pairedItem(<index>).
• $evaluateExpression() dans le nœud Code : retiré, uniquement pour les task runners en mode non sécurisé. Évaluez l’expression dans un champ du nœud.
• Execute Sub-workflow : les sources « Local File » et « URL » disparaissent. Utilisez « Database » ou « Define Below ».

Le Migration Report détecte ces usages dans les workflows existants. Si vous générez des workflows avec un assistant, comme je le décris dans Automatiser n8n avec Claude Code, vérifiez que votre serveur MCP n8n-mcp est à jour : une base de nœuds périmée vous ferait régénérer des nœuds déjà retirés.

Cinq valeurs par défaut changent dans n8n 3.0 : le timeout des nœuds Code passe de 300 à 60 secondes et la taille d’archive autorisée est divisée par huit.

Sécurité par défaut renforcée : ce qui peut casser au redémarrage

n8n 3.0 active plusieurs protections par défaut, et chacune peut interrompre un workflow en production si vous ne l’avez pas anticipée. Ce durcissement s’inscrit dans un contexte précis : en mars 2026, deux vulnérabilités critiques, CVE-2026-27577 (CVSS 9,4) et CVE-2026-27493 (CVSS 9,5), permettant une exécution de code à distance une fois chaînées, ont été corrigées en version 2.10.1.

Réglage	Avant 3.0	Dans n8n 3.0	Impact concret
Rotation de la clé de chiffrement	Optionnelle	Activée par défaut (désactivable depuis 2.40.3)	Vérifiez vos sauvegardes de clé et vos procédures de restauration
Signing secret Slack	Facultatif	Obligatoire pour Slack Trigger v2	Sans secret, le workflow refuse de se publier et le trigger renvoie une erreur 401
Liste de blocage SSRF	Plages par défaut	Ajout de 100.64.0.0/10, ::/128, 2002::/16, 64:ff9b::/96	Les appels vers un réseau Tailscale/Headscale (CGNAT) sont bloqués sauf exception explicite
Taille max décompressée	2 Gio	256 Mio	Les workflows qui traitent de grosses archives échouent
Entrées max par ZIP	5 000	1 000	Idem pour les archives volumineuses
Paquets communautaires non vérifiés	Chargés	N8N_UNVERIFIED_PACKAGES_ENABLED=false	Les nœuds communautaires non vérifiés ne se chargent plus
Timeout des task runners	300 s	60 s	Un nœud Code qui tourne plus d’une minute est interrompu

Le point Slack est à traiter en priorité si vous avez des bots en production. Rendez-vous dans les paramètres de votre application Slack (Basic Information > App Credentials), copiez le Signing Secret et ajoutez-le à vos identifiants Slack dans n8n avant la mise à jour. C’est une manipulation de deux minutes qui évite une panne silencieuse de tous vos déclencheurs Slack.

Pour le timeout des task runners, mon conseil est de fixer explicitement N8N_RUNNERS_TASK_TIMEOUT=300 si vous avez des nœuds Code longs, plutôt que de découvrir la limite de 60 secondes en production un dimanche soir.

Fonctions retirées de l’éditeur : Chat Hub, Import from URL, Ask AI

Trois fonctions disparaissent de l’interface, sans incidence sur l’exécution des workflows existants mais avec un impact sur vos habitudes.

Chat Hub est désactivé par défaut. Pour le conserver sur toute la branche 3.x, ajoutez chat-hub à la variable N8N_ENABLED_MODULES. n8n annonce déjà sa suppression définitive en version 4.0 : considérez-le comme en sursis et ne construisez rien de nouveau dessus.

Import from URL est retiré du menu de l’éditeur. Les autres méthodes d’import restent disponibles : copier-coller du JSON, import depuis un fichier, CLI et API publique. Si vous partagez des templates par lien direct, prévoyez un fichier ou un dépôt Git à la place.

L’onglet Ask AI du nœud Code disparaît. Cette aide à la génération de code était de toute façon réservée aux instances Cloud. Le code déjà généré continue de fonctionner.

Un dernier retrait touche les droits : l’option « Enable external secrets for project roles » n’existe plus. Les éditeurs et administrateurs de projet obtiennent l’accès aux secrets externes par défaut. Si vous deviez restreindre cet accès, créez des rôles personnalisés avant de migrer.

Variables d’environnement et stockage : la checklist docker-compose

Plusieurs variables changent de valeur par défaut, sont renommées ou disparaissent. Le plus sûr est de les fixer explicitement dans votre docker-compose.yml avant la mise à jour, pour que le comportement ne change pas à votre insu.

services:
  n8n:
    image: n8nio/n8n:2.45.0   # épingler, ne jamais laisser "latest"
    environment:
      # Valeurs par défaut qui changent en 3.0 : fixer celles que vous voulez garder
      - N8N_RUNNERS_TASK_TIMEOUT=300
      - N8N_UNVERIFIED_PACKAGES_ENABLED=false
      - N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES=268435456
      - N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES=1000
      # Variables renommées ou invalides en 3.0
      - DB_PING_TIMEOUT_MS=2000            # remplace N8N_DB_PING_TIMEOUT
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem   # "default" n'est plus accepté
      # À supprimer : OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS, N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION
    volumes:
      - n8n_data:/home/node/.n8n

Le changement le plus piégeux concerne le stockage des fichiers binaires. Le dossier ~/.n8n/binaryData est renommé ~/.n8n/storage, la variable N8N_MIGRATE_FS_STORAGE_PATH disparaît, et n8n 3.0 refuse de démarrer si les deux dossiers coexistent. Trois cas :

1. Le dossier binaryData est dans votre volume principal : démarrez une dernière fois en 2.x avec N8N_MIGRATE_FS_STORAGE_PATH=true, puis retirez la variable et redémarrez.
2. Vous montez un volume ou un dossier hôte directement sur binaryData : changez la cible du montage vers /home/node/.n8n/storage, puis supprimez le dossier binaryData vide que Docker laisse dans le volume.
3. Vous voulez conserver l’ancien chemin : fixez N8N_STORAGE_PATH=/home/node/.n8n/binaryData.

Quatre changements de comportement complètent la liste.

• Gmail Trigger (versions 1 à 1.3) s’exécute désormais comme la 1.4 : les brouillons sont ignorés sauf activation de « Include Drafts », les mails envoyés ou programmés ne déclenchent plus rien, et « Max Emails per Poll » vaut 10 par défaut (50 maximum).
• Always Output Data sur les nœuds à sorties multiples (If, Switch) n’ajoute un item vide que si toutes les sorties sont vides.
• Webflow OAuth2 : le toggle « Legacy » de l’identifiant est désactivé par défaut ; les nouveaux identifiants demandent les scopes cms:read cms:write sites:read forms:read.
• Chat Trigger en WebSocket : chaque trame est désormais un objet JSON avec un champ type. Si vous embarquez le widget @n8n/chat vous-même, passez en version 1.31.0 ou supérieure.

Les 7 étapes de la migration n8n 3.0 : les quatre premières restent réversibles en 2.x, la bascule finale est à sens unique.

La procédure de migration pas à pas

L’ordre compte autant que le contenu. Voici les sept étapes que je recommande, de la moins risquée à la plus engageante.

Étape 1 : mettre à jour vers la dernière version 2.x

Le Migration Report existe depuis la 2.39, mais n8n précise que la dernière 2.x embarque la version la plus récente du rapport. Les 2.43 (6 octobre), 2.44 (13 octobre) et 2.45 (20 octobre) ont successivement ajouté des catégories d’impact à la place des niveaux de sévérité, une colonne d’état « Open / Won’t fix » et la notification des propriétaires de workflows. Passez donc en 2.45 (ou plus récent) avant toute chose.

Si vous êtes encore en 1.x, c’est ici que le chantier commence : il n’existe aucun chemin direct de la v1 vers la v3, et le support de la v1 s’arrête le 31 décembre 2026.

Étape 2 : ouvrir Settings > Migration Report et traiter chaque ligne

Le rapport liste les workflows et les réglages d’instance incompatibles avec 3.0. Contrairement au rapport de la v2, il est accessible aux non-administrateurs : les admins voient tous les workflows, les autres utilisateurs ceux auxquels ils ont accès. Depuis la 2.45, un administrateur peut assigner des workflows à leurs propriétaires et leur envoyer une notification par e-mail, individuellement ou en masse.

Pour chaque élément, trois actions possibles : appliquer la correction automatique, corriger à la main, ou marquer « Won’t fix » pour les workflows abandonnés. Le rapport indique aussi dans les logs de démarrage les variables d’environnement dépréciées.

Étape 3 : appliquer les corrections automatiques et relire

L’auto-fix convertit les nœuds qui ont un remplaçant mécanique (Cron vers Schedule Trigger, Function vers Code, AI Transform vers Code). Chaque correction est enregistrée comme une nouvelle version du workflow, non publiée. Relisez-la, testez-la manuellement, puis publiez.

Ne faites pas une confiance aveugle au compteur en haut du rapport : le guide de jacar.es a observé que l’en-tête soustrait un workflow par règle enfreinte, ce qui sous-estime le nombre de workflows réellement compatibles. Fiez-vous à la liste détaillée.

Étape 4 : migrer de npm vers Docker et ajuster les variables

Si vous êtes sur npm, c’est le moment d’appliquer la procédure de la section Docker ci-dessus, en restant en 2.x. Dans tous les cas, intégrez la checklist de variables, le signing secret Slack et la migration binaryData vers storage.

Étape 5 : sauvegarder intégralement, service arrêté

Une sauvegarde à chaud d’une base en cours d’écriture n’est pas fiable. Arrêtez le service, exportez, redémarrez.

docker compose stop n8n
# Postgres
docker compose exec -T postgres pg_dump -U n8n -Fc n8n > n8n-2.45.dump
# Volume n8n (SQLite, clé de chiffrement, fichiers binaires)
docker run --rm -v n8n_data:/from:ro -v "$PWD":/to alpine:3 \
  tar -C /from -czf /to/n8n_data-2.45.tgz .
docker compose start n8n

Conservez aussi une copie séparée de N8N_ENCRYPTION_KEY. Une sauvegarde sans la clé ne vaut rien : vos identifiants seraient illisibles.

Étape 6 : tester sur une copie avant la production

Restaurez la sauvegarde dans un projet Docker Compose séparé (docker compose -p n8n-v3-test), avec ses propres ports et volumes, puis pointez ce projet sur l’image 3.0. Un détail que j’ai retenu du retour de jacar.es : un démarrage raté de l’image nightly 3.0 avait déjà appliqué 7 migrations et supprimé deux tables. Remettre l’ancien tag d’image ne suffit donc pas à revenir en arrière ; seule la restauration du dump compte.

Testez en priorité les workflows qui touchent Slack, les agents IA, les fichiers binaires et les nœuds Code longs. Ce sont les quatre familles les plus exposées aux changements listés plus haut.

Étape 7 : mettre à jour la production et épingler la version

Une fois le staging validé, répétez la sauvegarde sur la production, mettez à jour, et surveillez les premières exécutions. Épinglez ensuite la version dans votre docker-compose.yml. Un outil de mise à jour automatique comme Watchtower sur le tag latest pourrait tirer la 3.0 sans que vous l’ayez décidé, et il n’y aurait pas de retour possible.

Cinq dates clés de n8n 3.0 : deux mois entre la bêta et la stable, puis 12 mois de correctifs pour la 2.x.

Calendrier de support : quand migrer selon votre situation

Vous n’êtes pas obligé de migrer le 27 octobre. La fenêtre réelle s’étend jusqu’à la fin 2027 pour la plupart des instances 2.x, mais elle est beaucoup plus courte pour les instances 1.x.

Votre situation	Échéance	Recommandation
Instance 1.x	Fin de support le 31/12/2026	Passer en 2.x immédiatement, puis préparer la 3.0
Instance 2.x sur npm/npx	Plus de mises à jour après la dernière 2.x	Migrer vers Docker avant décembre, 3.0 ensuite
Instance 2.x Docker, workflows simples	12 mois de correctifs après la 3.x stable	Migrer en décembre ou janvier, après la stable
Instance 2.x Docker, agents IA et nœuds legacy nombreux	Idem	Lancer le Migration Report dès maintenant, migrer au premier trimestre 2027
n8n Cloud	Géré par n8n	Traiter le Migration Report avant que la 3.x devienne la version par défaut

Mon avis : faut-il installer la bêta du 27 octobre ?

Mon verdict : installez la bêta uniquement sur une copie de votre instance, jamais en production. L’intérêt de la bêta est de confronter vos workflows réels à la 3.0 dès maintenant, sans attendre décembre, et de remonter les problèmes à n8n pendant qu’ils peuvent encore être corrigés avant la stable.

Pour la production, attendez la version stable de début décembre et, idéalement, la première ou la deuxième version corrective qui suivra. La mise à jour est à sens unique, la liste des changements est longue, et n8n maintient la 2.x pendant douze mois : rien ne justifie de se précipiter.

Ce qu’il faut retenir : lancez Settings > Migration Report cette semaine, même si vous ne migrez pas avant plusieurs mois. C’est l’étape sans risque qui vous dira si vous avez deux workflows à retoucher ou quarante. La réponse change complètement la façon dont vous planifierez le reste.