n8n 3.0 : migrer de npm vers Docker avant octobre 2026

Ce qui change avec n8n 3.0 et pourquoi agir maintenant

La documentation officielle des breaking changes de n8n 3.0 est sans ambiguïté : « Self-hosted n8n will require a Docker-based deployment. n8n 3.0 will no longer support installations run using npm or npx n8n. » Ce n'est pas un avertissement de dépréciation progressive — c'est une date butoir. En octobre 2026, toute instance lancée via npx n8n ou un package npm global ne pourra plus être mise à jour. Elle restera figée sur la dernière version 2.x, sans correctifs de sécurité.

Risques de reporter la migration à octobre

Mise à jour sous pression — migrer en urgence alors que des automatisations critiques tournent expose à des erreurs de configuration difficiles à diagnostiquer.
Perte de données SQLite — l'issue GitHub #22341 documente des cas où des conteneurs Docker mis à jour sans précautions ont provoqué une régression de la base : les workflows et exécutions « reviennent en arrière » vers l'état d'une ancienne sauvegarde.
Absence de correctifs — une instance npm figée en v2.x ne reçoit plus ni les patches de sécurité ni les correctifs de stabilité publiés pour la branche 3.x.
Incompatibilité croissante — les intégrations, nœuds communautaires et webhooks reposent sur des API qui évoluent ; rester sur une version morte crée une dette d'incompatibilité croissante.
Durée imprévisible — une migration bien préparée prend une heure ; une migration improvisée peut mobiliser une journée, pendant laquelle vos workflows sont arrêtés.

Prérequis avant de commencer

Cette procédure s'adresse à une instance n8n existante en production. Si vous partez de zéro, consultez l'article dédié à l'installation initiale de n8n sur VPS.

Ce dont vous avez besoin

VPS avec accès root — Ubuntu 22.04 ou Debian 12 recommandés, minimum 2 vCPU et 2 Go de RAM pour n8n seul, 4 Go si vous ajoutez PostgreSQL sur le même hôte.
Docker Engine et Docker Compose v2 — vérifiez avec docker --version et docker compose version (syntaxe sans tiret, plugin v2).
PostgreSQL recommandé — n8n supporte SQLite et PostgreSQL, mais SQLite sur Docker présente des risques de perte de données en cas de mise à jour mal gérée (cf. issue #22341) ; PostgreSQL est la cible pour toute instance qui compte.
Accès à l'instance npm actuelle — la migration exige d'exporter les workflows via l'API REST avant d'arrêter l'ancienne instance.
Un nom de domaine et un certificat TLS — n8n en production ne s'expose pas en HTTP brut ; Nginx fait office de reverse proxy avec Let's Encrypt.
Une fenêtre de maintenance planifiée — même courte, elle évite les pertes d'exécutions en cours.

Détecter votre mode de lancement actuel

Avant toute chose, identifiez précisément comment votre instance n8n est lancée. La commande à utiliser dépend du mode de supervision.

Détecter, exporter, déployer et valider

Identifier le processus n8n

Cherchez l'exécutable en cours : which n8n indique le chemin si n8n est installé globalement via npm. Puis vérifiez si un service système le supervise : systemctl status n8n ou systemctl status n8n.service. Si aucun service systemd n'existe, cherchez un processus actif : ps aux | grep n8n. Un résultat contenant node .../n8n/bin/n8n ou npx n8n confirme une installation npm.

Repérer le fichier de configuration et la base de données

Le répertoire de données par défaut est ~/.n8n/. Vérifiez son contenu : ls -la ~/.n8n/. Le fichier database.sqlite indique une base SQLite. Notez le chemin complet — vous en aurez besoin pour l'export. Si la variable N8N_USER_FOLDER est définie dans l'environnement du processus (cat /proc/$(pgrep -f n8n)/environ | tr '\0' '\n' | grep N8N), c'est ce chemin qui prévaut.

Exporter tous vos workflows via l'API REST

L'API REST de n8n permet d'exporter les workflows en JSON. Récupérez d'abord une clé API dans l'interface (Settings → API → Create API Key), puis exportez : curl -s -H 'X-N8N-API-KEY: VOTRE_CLE' http://localhost:5678/api/v1/workflows | python3 -m json.tool > workflows-export-$(date +%Y%m%d).json. Vérifiez que le fichier contient bien vos workflows : python3 -c "import json; d=json.load(open('workflows-export-*.json')); print(len(d['data']), 'workflows exportés')". Conservez ce fichier en lieu sûr avant toute opération.

Arrêter proprement l'instance npm

Si supervisé par systemd : systemctl stop n8n && systemctl disable n8n. Si lancé manuellement dans un terminal ou via un script de démarrage, identifiez le PID (pgrep -f n8n) puis kill -SIGTERM <PID>. Attendez quelques secondes que n8n termine ses exécutions en cours avant de forcer l'arrêt. Une fois arrêté, notez ou sauvegardez ~/.n8n/database.sqlite si vous souhaitez conserver les historiques d'exécution.

Créer le fichier docker-compose.yml avec PostgreSQL

Créez un répertoire dédié : mkdir -p /opt/n8n && cd /opt/n8n. Puis créez le fichier docker-compose.yml avec le contenu suivant — adaptez les mots de passe et le domaine :

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: n8n
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: CHANGEZ_CE_MOT_DE_PASSE
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n"]
      interval: 10s
      timeout: 5s
      retries: 5

  n8n:
    image: n8nio/n8n:2.38.4
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: n8n
      DB_POSTGRESDB_PASSWORD: CHANGEZ_CE_MOT_DE_PASSE
      N8N_HOST: votre-domaine.com
      N8N_PORT: 5678
      N8N_PROTOCOL: https
      WEBHOOK_URL: https://votre-domaine.com/
      N8N_BASIC_AUTH_ACTIVE: "true"
      N8N_BASIC_AUTH_USER: admin
      N8N_BASIC_AUTH_PASSWORD: CHANGEZ_CE_MOT_DE_PASSE_AUTH
    volumes:
      - n8n_data:/home/node/.n8n
    ports:
      - "127.0.0.1:5678:5678"

volumes:
  postgres_data:
  n8n_data:

Remarque : la version est épinglée à 2.38.4 (stable au 2026-09-09). Ne jamais utiliser :latest — voir le conseil ci-dessous.

Démarrer la stack et importer les workflows

Lancez la stack : docker compose up -d. Attendez que les deux conteneurs soient sains : docker compose ps. Une fois n8n accessible sur http://127.0.0.1:5678, importez vos workflows via l'API : curl -s -X POST -H 'X-N8N-API-KEY: VOTRE_NOUVELLE_CLE' -H 'Content-Type: application/json' -d @workflows-export-YYYYMMDD.json http://127.0.0.1:5678/api/v1/workflows. Si votre export contient plusieurs workflows dans un tableau, importez-les un par un ou utilisez le script d'import fourni dans la documentation n8n. Vérifiez ensuite dans l'interface que vos workflows, leurs connexions et leurs credentials sont présents.

Configurer Nginx comme reverse proxy avec TLS

Installez Nginx et Certbot si ce n'est pas fait : apt install nginx certbot python3-certbot-nginx -y. Créez la configuration Nginx dans /etc/nginx/sites-available/n8n :

server {
    listen 80;
    server_name votre-domaine.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name votre-domaine.com;

    location / {
        proxy_pass http://127.0.0.1:5678;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 300s;
    }
}

Activez le site et obtenez le certificat : ln -s /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/ && certbot --nginx -d votre-domaine.com.

Valider que la migration a réussi

Effectuez ces vérifications dans l'ordre : 1) accédez à https://votre-domaine.com — la page de connexion s'affiche sans avertissement TLS ; 2) connectez-vous et vérifiez que vos workflows sont présents et actifs ; 3) déclenchez manuellement un workflow simple pour valider l'exécution de bout en bout ; 4) vérifiez les webhooks : si des services tiers pointent vers votre ancienne URL ou un ancien port, mettez-les à jour dans n8n (Settings → Webhooks) ; 5) laissez tourner 24 heures et consultez les logs : docker compose logs n8n --since 24h | grep -i error.

Épinglez toujours une version, jamais :latest

L'utilisation de n8nio/n8n:latest dans votre docker-compose.yml expose à des mises à jour automatiques non contrôlées lors d'un docker compose pull. Sur une base SQLite, un saut de version majeur sans migration préalable peut déclencher le scénario décrit dans l'issue #22341 : les données semblent présentes dans le volume mais la base revient à un état antérieur. Épinglez toujours une version précise (n8nio/n8n:2.38.4) et planifiez vos montées de version. Pour passer à une nouvelle version, lisez d'abord les release notes, puis : docker compose pull && docker compose up -d.

Dépannage : les cas courants après migration

Voici les problèmes rencontrés le plus fréquemment lors de cette transition.

Problèmes et solutions

Workflows vides après import — vérifiez que le format JSON exporté correspond au format attendu par l'API d'import ; certaines versions n8n exportent un objet { data: [] }, d'autres un tableau direct. Adaptez la commande curl en conséquence.
Webhooks qui ne répondent plus — la variable WEBHOOK_URL doit correspondre exactement à l'URL publique de votre instance (avec https://). Un mauvais paramétrage génère des URLs de webhook incorrectes dans l'interface.
Credentials inaccessibles — les credentials sont chiffrés avec la clé N8N_ENCRYPTION_KEY. Si vous ne la définissez pas explicitement et que vous repartez d'un nouveau volume n8n_data, les anciens credentials sont perdus. Récupérez la clé depuis ~/.n8n/.n8n_encryption_key sur l'instance npm et posez-la en variable d'environnement.
Base SQLite qui régresse (issue #22341) — si vous avez choisi de conserver SQLite temporairement, assurez-vous que le volume Docker est monté de façon persistante et que vous n'utilisez pas --rm ou de politique de restart agressive. La migration vers PostgreSQL reste la résolution définitive.
Erreur ECONNREFUSED sur PostgreSQL — la condition depends_on.postgres.condition: service_healthy et le healthcheck pg_isready garantissent que n8n attend que PostgreSQL soit prêt. Sans cette condition, n8n démarre avant PostgreSQL et échoue.

Une migration à faire maintenant, pas en octobre

La version stable de n8n au moment de cet article est la 2.38.4. Vous avez plusieurs semaines pour mener cette migration dans de bonnes conditions : exporter proprement vos workflows, tester la stack Docker sur un serveur de test, puis basculer la production avec un vrai plan de rollback. En octobre, quand n8n 3.0 sera disponible, vous n'aurez qu'à bumper le numéro de version dans votre docker-compose.yml — un geste de cinq minutes. La différence entre cinq minutes et une journée de stress se joue maintenant.