Les variables d'environnement n8n à connaître (et comment les utiliser)

Une instance n8n self-hosted se configure presque entièrement par variables d'environnement : l'URL publique, la base de données, le fuseau horaire, la rétention des exécutions, le chiffrement des credentials, le mode queue. La documentation officielle en liste des dizaines — mais dans la pratique, une quinzaine d'entre elles couvrent l'essentiel des besoins, et deux ou trois erreurs classiques (clé de chiffrement non sauvegardée, WEBHOOK_URL absente derrière un reverse proxy, timezone par défaut) expliquent une bonne partie des tickets de support qu'on croise sur les forums. Ce guide regroupe les variables réellement utiles par thème, montre comment les définir proprement en Docker, et comment y accéder depuis un workflow.

Comment définir une variable d'environnement (self-hosted uniquement)

En installation Docker, deux approches complémentaires. La première : déclarer les variables directement dans le bloc environment du service n8n dans docker-compose.yml :

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    environment:
      - GENERIC_TIMEZONE=Europe/Paris
      - TZ=Europe/Paris
      - WEBHOOK_URL=https://n8n.mondomaine.fr/

La seconde, préférable dès qu'il y a des secrets : placer les valeurs dans un fichier .env à côté du docker-compose.yml (Docker Compose le lit automatiquement) et les référencer avec la syntaxe ${...} :

    environment:
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - DB_POSTGRESDB_PASSWORD=${DB_POSTGRESDB_PASSWORD}

Le .env ne doit jamais être commité dans un dépôt Git — ajoutez-le au .gitignore dès le premier jour. Et dans tous les cas, un redémarrage du conteneur est nécessaire (docker compose up -d suffit) : n8n lit ses variables d'environnement au démarrage, jamais à chaud.

Sur n8n Cloud, rien de tout cela n'est accessible : l'infrastructure est gérée par n8n, et vous ne pouvez ni définir vos propres variables ni modifier celles de l'instance. C'est l'une des différences structurantes entre Cloud et self-hosted — si votre besoin passe par une configuration fine (mode de stockage binaire, mode queue, timeouts), le self-hosted est la seule voie.

Instance et URLs

Le thème qui cause le plus de confusion, surtout derrière un reverse proxy :

Variable	Rôle
N8N_HOST	Nom d'hôte sur lequel n8n se considère joignable
N8N_PORT	Port d'écoute du processus n8n (5678 par défaut)
N8N_PROTOCOL	http ou https, utilisé pour construire les URLs
WEBHOOK_URL	URL publique complète utilisée pour générer les URLs de webhook
N8N_EDITOR_BASE_URL	URL publique de l'éditeur, utilisée dans les liens générés par n8n

Le piège classique : une instance derrière Traefik ou Caddy avec HTTPS et nom de domaine qui affiche des URLs de webhook en http://localhost:5678/.... Le conteneur n8n ne sait pas qu'un reverse proxy le publie sur https://n8n.mondomaine.fr — c'est précisément le rôle de WEBHOOK_URL de le lui dire. Sans elle, tous les webhooks affichés dans l'éditeur (et transmis aux services tiers) pointent vers une adresse injoignable de l'extérieur.

Base de données

Par défaut, n8n utilise SQLite — suffisant pour tester, fragile en production. Le passage à PostgreSQL se fait entièrement par variables :

Variable	Rôle
DB_TYPE	sqlite par défaut ; postgresdb pour PostgreSQL
DB_POSTGRESDB_HOST	Hôte du serveur PostgreSQL
DB_POSTGRESDB_PORT	Port (5432 par défaut)
DB_POSTGRESDB_DATABASE	Nom de la base
DB_POSTGRESDB_USER	Utilisateur
DB_POSTGRESDB_PASSWORD	Mot de passe (à mettre dans le .env, jamais en clair dans le compose)

Attention au point de bascule : changer DB_TYPE sur une instance existante ne migre pas les données — workflows et credentials restent dans l'ancienne base. La migration SQLite → PostgreSQL et la stratégie de sauvegarde associée méritent un plan, détaillé dans notre guide sauvegarde et restauration PostgreSQL.

Timezone

Deux variables, deux rôles distincts :

Variable	Rôle
GENERIC_TIMEZONE	Fuseau horaire utilisé par n8n lui-même, notamment par le Schedule Trigger
TZ	Fuseau horaire du système dans le conteneur (horodatage des logs, commandes système)

Sans GENERIC_TIMEZONE, un Schedule Trigger configuré pour « tous les jours à 9 h » ne se déclenchera pas à 9 h heure de Paris — n8n applique son fuseau par défaut, qui n'est pas UTC mais America/New_York. Définir les deux variables sur la même valeur (Europe/Paris) évite les décalages entre l'heure des déclenchements et celle des logs. Les subtilités (heure d'été, expressions cron, fuseaux par workflow) sont couvertes dans notre guide du Schedule Trigger et des fuseaux horaires.

Exécutions et nettoyage

L'historique des exécutions est la première cause de base de données obèse sur une instance qui tourne depuis des mois :

Variable	Valeur par défaut	Rôle
EXECUTIONS_DATA_PRUNE	true	Active la purge automatique des anciennes exécutions
EXECUTIONS_DATA_MAX_AGE	336 (heures, soit 14 jours)	Âge maximal des exécutions conservées
EXECUTIONS_TIMEOUT	-1 (désactivé)	Durée maximale d'une exécution en secondes, au-delà de laquelle elle est interrompue

La purge est activée par défaut sur les versions récentes, mais vérifier ces deux valeurs sur une instance héritée d'une vieille installation est un réflexe sain. EXECUTIONS_TIMEOUT mérite d'être défini explicitement : sans lui, un workflow bloqué sur un appel externe qui ne répond jamais peut rester « en cours » indéfiniment et occuper des ressources pour rien.

Données binaires

Deux variables déjà détaillées dans notre guide sur les fichiers volumineux et le binary data, résumées ici :

Variable	Valeur par défaut	Rôle
N8N_DEFAULT_BINARY_DATA_MODE	default (mémoire)	Mode de stockage des fichiers pendant l'exécution : default, filesystem, ou s3 (Enterprise)
N8N_PAYLOAD_SIZE_MAX	16 (Mo)	Taille maximale d'un payload JSON accepté

Le passage en filesystem est le premier réglage à activer dès qu'un workflow manipule régulièrement des fichiers de plusieurs dizaines de Mo — avant même d'augmenter la RAM du serveur.

Sécurité

Variable	Rôle
N8N_ENCRYPTION_KEY	Clé de chiffrement de tous les credentials stockés en base
N8N_BLOCK_ENV_ACCESS_IN_NODE	Si true, bloque l'accès à $env depuis les workflows

N8N_ENCRYPTION_KEY est la variable la plus critique de toute cette liste. Si elle n'est pas définie explicitement, n8n en génère une au premier démarrage et la stocke dans son dossier de données — et le jour où vous restaurez une sauvegarde de la base sur un nouveau serveur sans cette clé, tous les credentials deviennent indéchiffrables : chaque connexion API, chaque OAuth, chaque mot de passe est à ressaisir à la main. Définissez-la explicitement dès l'installation, stockez-la dans un gestionnaire de secrets, et ne la changez jamais sur une instance en production. C'est le complément indispensable des pratiques décrites dans notre guide pour sécuriser les credentials API dans n8n.

N8N_BLOCK_ENV_ACCESS_IN_NODE=true est le garde-fou associé : sur une instance partagée entre plusieurs équipes ou exposée à des workflows importés de sources externes, il empêche un node Code ou une expression de lire $env.DB_POSTGRESDB_PASSWORD ou la clé de chiffrement elle-même.

Mode queue

Pour scaler au-delà d'un seul processus, n8n propose un mode queue basé sur Redis :

Variable	Rôle
EXECUTIONS_MODE	queue pour activer le mode queue (défaut : regular)
QUEUE_BULL_REDIS_HOST	Hôte du serveur Redis utilisé comme file d'attente

Le processus principal reçoit les déclenchements et pousse les exécutions dans Redis, des workers séparés les consomment. Architecture, dimensionnement et pièges (dont le stockage binaire partagé) sont détaillés dans notre guide du mode queue avec Redis.

Accéder aux variables depuis un workflow : $env

Toutes les variables d'environnement du processus n8n sont lisibles dans les expressions via $env :

{{ $env.API_BASE_URL }}

C'est le mécanisme idéal pour tout ce qui change entre environnements sans être un secret au sens strict : une URL de base d'API, un nom de bucket, un identifiant de canal Slack de notifications. Le même objet $env est accessible dans un node Code — voir notre guide des expressions et du node Code pour les patterns d'usage. Rappel : si N8N_BLOCK_ENV_ACCESS_IN_NODE=true est défini, cet accès est bloqué partout.

$env n'est pas $vars

À ne pas confondre avec les « Variables » de l'interface n8n, accessibles via $vars dans les expressions : celles-ci se créent et se modifient depuis l'UI sans toucher au serveur, mais relèvent des fonctionnalités payantes de n8n (elles ne font pas partie de la Community Edition gratuite). $env lit l'environnement du processus — gratuit, self-hosted uniquement, redémarrage requis à chaque changement ; $vars lit des valeurs gérées dans l'interface — modifiables à chaud, mais conditionnées au plan. Sur une Community Edition, $env reste la voie standard.

Bonnes pratiques : traiter son .env comme du code

Trois règles évitent l'essentiel des incidents :

1. Aucun secret en dur dans les workflows. Une clé API collée dans un node HTTP Request se retrouve dans chaque export JSON du workflow, chaque copie d'écran, chaque partage. Les secrets vont dans les credentials n8n (chiffrés par N8N_ENCRYPTION_KEY), la configuration non secrète dans $env.
2. Documenter le .env. Un commentaire par variable : à quoi elle sert, qui l'a définie, ce qui casse si on la change. Un fichier .env.example commité (avec des valeurs factices) sert de contrat pour reconstruire l'instance.
3. Redémarrer après chaque changement, et le noter. Une variable modifiée sans redémarrage donne une instance dont la configuration affichée ne correspond pas au comportement réel — le pire scénario de débogage.

Ce n'est pas un excès de zèle. Dans leur article présenté à NeurIPS 2015, Hidden Technical Debt in Machine Learning Systems (voir sur Google Scholar), Sculley et ses co-auteurs chez Google identifient la configuration comme l'une des principales sources de dette technique des systèmes en production — au point que le nombre de lignes de configuration peut dépasser le nombre de lignes de code, alors qu'elle est rarement testée ou revue avec la même rigueur. Le constat s'applique mot pour mot à une instance n8n : un .env non documenté, c'est une panne qui attend son heure. Pour les équipes soumises à des exigences de traçabilité, le Pack Conformité & Audit (149 €) pousse cette logique jusqu'au bout, avec des workflows d'inventaire et de piste d'audit qui documentent l'état de l'instance en continu.

Pour aller plus loin

Les variables d'environnement sont la couche de configuration de base d'un n8n self-hosted : une fois N8N_ENCRYPTION_KEY sauvegardée, WEBHOOK_URL alignée sur le reverse proxy, la timezone posée et la purge des exécutions vérifiée, l'instance est saine pour durer. L'étape suivante consiste à structurer le reste du cycle de vie — et notamment la séparation entre une instance de test et une instance de production, chacune avec son propre .env, un sujet couvert dans nos guides d'exploitation. Un .env propre est aussi ce qui rend les mises à jour et les migrations sereines : c'est lui qui garantit qu'une instance reconstruite depuis zéro se comporte exactement comme l'ancienne.