Une instance n8n auto-hébergée finit par faire tourner des processus que personne n'ose toucher : facturation, relances, synchronisations. Et plus on retarde la mise à jour, plus le saut de version est risqué. La documentation de n8n le dit elle-même : mettre à jour fréquemment évite d'avoir à sauter plusieurs versions d'un coup, et elle recommande une mise à jour au moins une fois par mois.
Cet article propose une checklist en six étapes pour mettre à jour une instance auto-hébergée, avec un point d'attention particulier si vous passez encore de la branche 1.x à la 2.x. Les faits sur n8n viennent de sa documentation officielle, citée en fin d'article ; les recommandations de méthode sont notre analyse, à adapter à votre contexte.
Étape 1 : faire l'inventaire avant de toucher à quoi que ce soit
Notez ce qui rend votre instance spécifique, car ce sont ces éléments qui cassent en premier :
- la version actuelle et le mode d'installation (npm, Docker, Docker Compose) ;
- la base de données : SQLite, PostgreSQL ou, plus rarement, MySQL/MariaDB ;
- le mode d'exécution : instance unique ou mode queue avec workers ;
- les variables d'environnement définies dans votre fichier Compose ou
.env; - les nœuds sensibles utilisés dans vos workflows : exécution de commandes, accès fichiers, nœud Code, nœuds communautaires.
Cet inventaire prend une demi-heure et transforme la lecture des notes de version en vérification ciblée plutôt qu'en lecture passive.
Étape 2 : sauvegarder, pour de bon
Une mise à jour sans sauvegarde restaurable est un pari. La documentation de n8n détaille ce qu'il faut sauvegarder :
- le dossier
.n8n(volumen8n_data, monté sur/home/node/.n8nen Docker), qui contient le fichierconfigavec la clé de chiffrement des credentials, la base SQLite par défaut et, selon le mode de stockage, des données binaires ou d'exécution ; - la base PostgreSQL, avec ses propres outils, si vous en utilisez une ;
- les dossiers de nœuds personnalisés chargés via
N8N_CUSTOM_EXTENSIONS, et les éventuels stockages externes.
Trois points de la documentation évitent de mauvaises surprises :
- Sans la clé de chiffrement, les credentials sauvegardés sont inutilisables. La documentation précise que n8n les enregistre chiffrés ; sauvegardez le dossier
.n8nmême avec PostgreSQL. - Avec SQLite, arrêtez n8n avant de copier le dossier. Une copie pendant l'écriture peut être incohérente.
- L'export CLI ne suffit pas. Il couvre les workflows et les credentials, pas les utilisateurs et leurs rôles, l'historique d'exécution, les variables ni les paramètres de l'instance.
Les commandes d'export, à lancer vers deux dossiers distincts, sont :
n8n export:workflow --backup --output=backups/workflows/
n8n export:credentials --backup --output=backups/credentials/
En Docker, le dossier backups/ du conteneur n'est pas persistant : utilisez un bind mount ou copiez les fichiers avant de recréer le conteneur. Pour aller plus loin sur la sauvegarde et le versionnement, voir Sauvegarder et versionner ses workflows n8n.
Étape 3 : lire les breaking changes, avec vos workflows sous les yeux
Les notes de version indiquent les changements incompatibles. Pour la migration vers la 2.0, la documentation en liste une vingtaine. Voici ceux qui touchent le plus souvent une instance de PME, avec ce qu'il faut vérifier chez vous :
| Changement dans la 2.0 | Ce que vous devez vérifier |
|---|---|
Accès aux variables d'environnement bloqué par défaut dans le nœud Code (N8N_BLOCK_ENV_ACCESS_IN_NODE) |
Les nœuds Code ou expressions qui lisent $env |
Task runners activés par défaut, nœud Code exécuté dessus (N8N_RUNNERS_ENABLED) |
Les nœuds Code et leurs dépendances |
| Nœud Code Python (Pyodide) supprimé | Les nœuds Code écrits en Python |
ExecuteCommand et LocalFileTrigger désactivés par défaut (NODES_EXCLUDE) |
Les workflows qui exécutent des commandes ou surveillent des fichiers |
Accès aux fichiers limité par défaut au dossier ~/.n8n-files (N8N_RESTRICT_FILE_ACCESS_TO) |
Les nœuds qui lisent ou écrivent des fichiers |
| MySQL/MariaDB non supporté comme base de stockage | Le type de base de votre instance (le nœud MySQL reste supporté) |
| Nœud Start supprimé | Les vieux workflows : remplacez par Manual Trigger ou Execute Workflow Trigger |
| Sortie d'un sous-workflow après une attente modifiée | Les sous-workflows qui utilisent Wait |
| Activate/Deactivate remplacés par Publish/Unpublish | Vos procédures internes et scripts CLI (update:workflow est remplacée) |
Canaux latest et next remplacés par stable et beta |
Vos fichiers Compose : la documentation recommande d'épingler une version précise |
Pour repérer les workflows concernés, une méthode simple consiste à exporter vos workflows en fichiers séparés (voir l'étape 2) puis à y chercher les marqueurs : $env, le type de nœud d'exécution de commande, le nœud Start. Vérifiez le nom exact du type de nœud dans un JSON exporté de votre instance avant de lancer votre recherche. À la lecture de la page consultée, la documentation ne mentionne pas d'outil de détection automatique des workflows impactés : cette vérification reste donc manuelle.
Si votre instance utilise MySQL ou MariaDB, traitez ce point en premier : la documentation indique qu'ils ne sont plus supportés comme base de stockage et mentionne un outil de migration vers PostgreSQL ou SQLite. C'est un chantier à part, à planifier avant la mise à jour elle-même.
Étape 4 : tester sur une copie
La documentation conseille de créer une version de test de l'instance et d'y tester la mise à jour d'abord ; elle renvoie vers la fonction Environments. Selon votre installation, cette fonction peut ne pas être disponible : dans ce cas, une alternative simple est de restaurer votre sauvegarde sur une seconde instance isolée (autre serveur ou autres conteneurs, avec une base distincte), puis de mettre à jour celle-ci.
Sur la copie, attention aux effets de bord : désactivez les déclencheurs planifiés et les webhooks qui pointent vers des services réels, sinon la copie enverra les mêmes e-mails que la production. Puis exécutez manuellement vos cinq workflows les plus critiques avec des données de test, et comparez les résultats.
Étape 5 : mettre à jour, en épinglant la version
Avec Docker Compose, la documentation donne la séquence suivante, à lancer dans le répertoire du fichier Compose :
docker compose pull
docker compose down
docker compose up -d
Deux précautions de méthode :
- Épinglez le numéro de version dans l'image (par exemple
n8nio/n8n:2.44.6, valeur indiquée comme version stable dans la documentation consultée) plutôt que de suivre un canal mobile. Une mise à jour devient alors une décision datée et réversible, pas un effet de bord d'un redémarrage. - Ne montez pas à la version la plus récente par réflexe. La documentation indique que
stableest destinée à la production et quebetapeut être instable. Choisissezstable.
Faites la mise à jour pendant une plage où les erreurs coûtent peu, pas un vendredi soir. Si vous utilisez le mode queue, mettez à jour l'instance principale et les workers à la même version.
Étape 6 : vérifier après la mise à jour
Ne vous contentez pas de constater que l'interface s'ouvre. Contrôlez, dans l'ordre :
- la version affichée par l'instance, et l'absence d'erreur dans les logs du conteneur ;
- la liste des workflows : ceux qui doivent être actifs (publiés) le sont-ils ? ;
- les credentials : ouvrez-en un par service critique et testez la connexion ;
- un webhook de production, appelé avec une requête de test ;
- les premières exécutions planifiées, dans l'onglet Executions ;
- votre alerte d'échec, qui doit toujours fonctionner : voir Gérer les erreurs dans n8n.
Prévoir le retour arrière
Écrivez la procédure avant la mise à jour, pas pendant l'incident. La documentation décrit la restauration complète : arrêter n8n, restaurer le dossier .n8n, restaurer la base PostgreSQL le cas échéant, restaurer la configuration de déploiement (dont N8N_ENCRYPTION_KEY si vous l'avez définie), puis redémarrer. Cela suppose que votre sauvegarde soit antérieure à la mise à jour, et que l'ancienne version de l'image soit toujours disponible : c'est l'autre bénéfice de l'épinglage.
Les erreurs fréquentes
- Sauvegarder les workflows mais pas la clé de chiffrement : la restauration donne des credentials illisibles.
- Copier un dossier SQLite pendant que n8n tourne.
- Suivre un canal mobile (
latest,next) dans un fichier Compose de production. - Sauter des versions pendant des mois, puis découvrir vingt changements en une fois.
- Tester sur une copie qui envoie de vrais e-mails.
- Mettre à jour sans plan de retour arrière.
Besoin d'une instance n8n maintenue avec méthode ?
Vous dépendez d'une instance n8n que personne ne veut mettre à jour ? Décrivez-nous votre installation : nous réalisons l'inventaire, préparons la sauvegarde et la procédure de test, puis planifions une mise à jour réversible. Nos offres détaillent les formats d'accompagnement, et vous pouvez nous contacter directement. Si le choix entre cloud et auto-hébergement se pose encore, lisez d'abord n8n Cloud ou auto-hébergé : hébergement et RGPD.
Questions fréquentes
À quelle fréquence mettre à jour n8n ? La documentation recommande de mettre à jour fréquemment, au moins une fois par mois, pour éviter de sauter plusieurs versions d'un coup.
Faut-il sauvegarder avant chaque mise à jour ? Oui. Sauvegardez le dossier .n8n (avec la clé de chiffrement) et la base si elle est externe, et vérifiez que vous savez restaurer.
Que devient la clé de chiffrement si je recrée le conteneur ? Elle est stockée dans le fichier config du dossier .n8n, ou dans N8N_ENCRYPTION_KEY si vous la définissez. Tant que le volume n8n_data est conservé, elle l'est aussi. Sans elle, les credentials ne peuvent pas être déchiffrés.
Peut-on rester sur MySQL ou MariaDB avec la 2.x ? La documentation des changements de la 2.0 indique que ces bases ne sont plus supportées comme stockage de n8n ; PostgreSQL ou SQLite sont recommandés. Le nœud MySQL, utilisé dans vos workflows, reste supporté.
Latest ou stable ? La documentation décrit stable comme la version destinée à la production, et beta comme potentiellement instable. Pour un environnement de production, choisissez stable et épinglez un numéro de version.
Sources
- n8n, Update n8n, documentation consultée le 25 octobre 2026.
- n8n, Breaking changes in n8n 2.0, documentation consultée le 25 octobre 2026.
- n8n, Back up and restore, documentation consultée le 25 octobre 2026.
- n8n, Install with Docker, documentation consultée le 25 octobre 2026 (page signalée comme obsolète par n8n, qui renvoie vers l'installation avec Docker Compose).