Set environment variables in n8n by adding them to a .env file, exporting them in your shell, or defining them in docker-compose.yml. n8n uses the N8N_ prefix convention for its own configuration variables. Environment variables control logging, database connections, webhook URLs, security settings, and more.
Why Set Environment Variables in n8n
Environment variables are the primary way to configure a self-hosted n8n instance. They control everything from the database connection and webhook URL to logging levels and security settings. Instead of modifying source code or configuration files inside the application, you pass settings through the environment. This keeps sensitive data like database passwords out of your codebase, makes it easy to change settings between development and production, and follows the twelve-factor app methodology. n8n recognizes dozens of environment variables, all following the N8N_ prefix convention.
Prerequisites
- A self-hosted n8n instance (npm or Docker)
- Access to the server terminal or Docker configuration files
- Basic familiarity with environment variables in Linux/macOS
- Permission to restart the n8n process after changes
Step-by-step guide
Set variables using shell export
Set variables using shell export
The simplest way to set environment variables is to export them in your terminal session before starting n8n. This method is ideal for quick testing but variables are lost when the terminal session ends. Each variable is set with the export command followed by the variable name, an equals sign, and the value. No spaces around the equals sign. After exporting all needed variables, start n8n in the same terminal.
1# Export environment variables in your terminal2export N8N_PORT=56783export N8N_PROTOCOL=https4export N8N_HOST=n8n.example.com5export WEBHOOK_URL=https://n8n.example.com/6export N8N_LOG_LEVEL=info7export GENERIC_TIMEZONE=America/New_York89# Start n8n in the same terminal session10n8n startExpected result: n8n starts with the exported configuration. Variables are active only for the current terminal session.
Use a .env file for persistent configuration
Use a .env file for persistent configuration
For permanent configuration, create a .env file in the directory where you run n8n. When using the npm-based installation, n8n reads from the .env file in the current working directory. Each line contains one variable in KEY=VALUE format. Lines starting with # are comments. The .env file persists across restarts and is easy to version-control (but exclude files containing passwords from public repositories).
1# .env file for n8n configuration2# Save this file in the directory where you run n8n34# Server settings5N8N_HOST=0.0.0.06N8N_PORT=56787N8N_PROTOCOL=https8WEBHOOK_URL=https://n8n.example.com/910# Database11DB_TYPE=postgresdb12DB_POSTGRESDB_HOST=localhost13DB_POSTGRESDB_PORT=543214DB_POSTGRESDB_DATABASE=n8n15DB_POSTGRESDB_USER=n8n_user16DB_POSTGRESDB_PASSWORD=your-secure-password1718# Logging19N8N_LOG_LEVEL=info20N8N_LOG_OUTPUT=console,file21N8N_LOG_FILE_LOCATION=/var/log/n8n/n8n.log2223# Timezone24GENERIC_TIMEZONE=America/New_York25TZ=America/New_York2627# Security28N8N_SECURE_COOKIE=true29N8N_ENCRYPTION_KEY=your-random-encryption-keyExpected result: n8n reads all variables from the .env file at startup. Configuration persists across restarts without re-exporting variables.
Configure variables in docker-compose.yml
Configure variables in docker-compose.yml
When running n8n in Docker, define environment variables in your docker-compose.yml file under the environment key. You can either list them inline or reference an external .env file using env_file. The inline approach is simpler for a small number of variables. The env_file approach is cleaner for larger configurations and keeps secrets out of the compose file.
1# docker-compose.yml with inline environment variables2version: '3.8'3services:4 n8n:5 image: docker.n8n.io/n8nio/n8n6 restart: unless-stopped7 ports:8 - '5678:5678'9 environment:10 - N8N_HOST=0.0.0.011 - N8N_PORT=567812 - N8N_PROTOCOL=https13 - WEBHOOK_URL=https://n8n.example.com/14 - N8N_LOG_LEVEL=info15 - GENERIC_TIMEZONE=America/New_York16 - DB_TYPE=postgresdb17 - DB_POSTGRESDB_HOST=postgres18 - DB_POSTGRESDB_PORT=543219 - DB_POSTGRESDB_DATABASE=n8n20 - DB_POSTGRESDB_USER=${DB_USER}21 - DB_POSTGRESDB_PASSWORD=${DB_PASSWORD}22 volumes:23 - n8n_data:/home/node/.n8n2425# Alternative: reference a .env file26# services:27# n8n:28# env_file:29# - .env3031volumes:32 n8n_data:Expected result: n8n container starts with all specified environment variables. Secrets referenced from .env are injected at container startup.
Pass variables with docker run
Pass variables with docker run
When using docker run instead of docker-compose, pass environment variables with the -e flag. Each variable requires its own -e flag. For more than a few variables, use the --env-file flag to point to a .env file. This approach is useful for quick testing or one-off container launches.
1# Using -e flags2docker run -d \3 --name n8n \4 -p 5678:5678 \5 -e N8N_HOST=0.0.0.0 \6 -e N8N_PORT=5678 \7 -e N8N_LOG_LEVEL=info \8 -e GENERIC_TIMEZONE=America/New_York \9 -v n8n_data:/home/node/.n8n \10 docker.n8n.io/n8nio/n8n1112# Using --env-file13docker run -d \14 --name n8n \15 -p 5678:5678 \16 --env-file .env \17 -v n8n_data:/home/node/.n8n \18 docker.n8n.io/n8nio/n8nExpected result: The n8n container starts with the specified environment variables. Using --env-file keeps the command concise.
Verify environment variables are loaded
Verify environment variables are loaded
After starting n8n with your environment variables, verify they are being read correctly. Enable info or debug logging and check the startup output for configuration-related messages. You can also check which variables are set inside a running Docker container. If a variable is not taking effect, the most common cause is a typo in the variable name or forgetting to restart n8n after changes.
1# Check environment variables inside a running Docker container2docker exec n8n env | grep N8N34# Check n8n startup logs for configuration5docker logs n8n 2>&1 | head -3067# For npm installations, check the current shell8env | grep N8N9env | grep DB_10env | grep WEBHOOKExpected result: The env command shows all N8N_ prefixed variables with their current values. n8n logs confirm the configuration is active.
Complete working example
1# .env — Complete n8n configuration reference2# Copy this file and customize for your deployment34# ===== Server =====5N8N_HOST=0.0.0.06N8N_PORT=56787N8N_PROTOCOL=https8WEBHOOK_URL=https://n8n.example.com/9N8N_EDITOR_BASE_URL=https://n8n.example.com/1011# ===== Database =====12DB_TYPE=postgresdb13DB_POSTGRESDB_HOST=localhost14DB_POSTGRESDB_PORT=543215DB_POSTGRESDB_DATABASE=n8n16DB_POSTGRESDB_USER=n8n_user17DB_POSTGRESDB_PASSWORD=change-this-password18DB_POSTGRESDB_SSL_REJECT_UNAUTHORIZED=false1920# ===== Security =====21N8N_ENCRYPTION_KEY=generate-with-openssl-rand-hex-3222N8N_SECURE_COOKIE=true2324# ===== Logging =====25N8N_LOG_LEVEL=info26N8N_LOG_OUTPUT=console,file27N8N_LOG_FILE_LOCATION=/var/log/n8n/n8n.log2829# ===== Timezone =====30GENERIC_TIMEZONE=America/New_York31TZ=America/New_York3233# ===== Execution =====34EXECUTIONS_DATA_SAVE_ON_SUCCESS=all35EXECUTIONS_DATA_SAVE_ON_ERROR=all36EXECUTIONS_DATA_PRUNE=true37EXECUTIONS_DATA_MAX_AGE=1683839# ===== Queue Mode (optional, for scaling) =====40# EXECUTIONS_MODE=queue41# QUEUE_BULL_REDIS_HOST=localhost42# QUEUE_BULL_REDIS_PORT=6379Common mistakes when setting Environment Variables in n8n
Why it's a problem: Forgetting to restart n8n after changing environment variables
How to avoid: n8n reads environment variables only at startup. Restart the process or container for changes to take effect.
Why it's a problem: Adding spaces around the equals sign in .env files
How to avoid: Use KEY=VALUE with no spaces. KEY = VALUE will not be parsed correctly by most .env readers.
Why it's a problem: Changing N8N_ENCRYPTION_KEY after credentials have been saved
How to avoid: The encryption key is used to encrypt stored credentials. Changing it makes all existing credentials unreadable. Set it once and back it up.
Why it's a problem: Setting WEBHOOK_URL without the trailing slash
How to avoid: Include the trailing slash: WEBHOOK_URL=https://n8n.example.com/. Some webhook integrations fail without it.
Best practices
- Always use a .env file or docker-compose environment section for persistent configuration
- Never commit .env files containing passwords or secrets to version control
- Set N8N_ENCRYPTION_KEY on first setup and back it up — losing it invalidates all saved credentials
- Use the N8N_ prefix convention when naming custom variables to avoid conflicts
- Restart n8n after every environment variable change since variables are only read at startup
- Use separate .env files for development and production environments
- Reference secrets in docker-compose.yml with ${VARIABLE} syntax and store actual values in .env
- Set GENERIC_TIMEZONE explicitly to avoid unexpected schedule behavior
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I am setting up a self-hosted n8n instance with Docker. What environment variables do I need to configure for a production deployment with PostgreSQL, HTTPS, and proper logging?
Help me create a complete .env file for my n8n Docker deployment. I need PostgreSQL database, HTTPS with a reverse proxy, info-level logging, and Eastern Time timezone.
Frequently asked questions
Where does n8n look for the .env file?
n8n reads the .env file from the current working directory when you run n8n start. For Docker, use the env_file directive in docker-compose.yml or the --env-file flag with docker run.
Do environment variables override .env file values?
Yes. Environment variables set via export or Docker -e flags take precedence over values in the .env file. This is useful for overriding specific settings without modifying the file.
Can I use environment variables in n8n expressions?
Not directly. n8n expressions like {{ $json.field }} access node data, not system environment variables. To use environment variable values in workflows, read them in a Code node using process.env.VARIABLE_NAME.
What is the N8N_ENCRYPTION_KEY and why is it important?
N8N_ENCRYPTION_KEY is used to encrypt credentials stored in the n8n database. If you do not set it, n8n generates one automatically and stores it in ~/.n8n. Always set it explicitly and back it up — losing it means all saved credentials become unreadable.
Can I set environment variables on n8n Cloud?
n8n Cloud manages infrastructure configuration for you. You cannot set server-level environment variables on n8n Cloud. Use the Settings UI for available configuration options.
How do I set different configurations for development and production?
Create separate .env files like .env.development and .env.production. Use the appropriate file when starting n8n or reference it in your Docker configuration.
Can RapidDev help me configure n8n for production?
Yes. RapidDev can set up a production-ready n8n deployment with optimized environment configuration, database tuning, and security hardening. Contact RapidDev for a free consultation.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation