n8n Environment Variables: A Complete Setup Guide for 2026

Effectively using n8n environment variables is a critical skill for anyone running a self-hosted n8n instance. They provide a powerful way to manage your instance's configuration and, most importantly, keep your sensitive credentials secure and separate from your workflow logic. This guide will walk you through everything you need to know to master them.

What Are n8n Environment Variables?

Environment variables are key-value pairs that exist outside of your n8n application code. They are read by n8n when it starts up and are used to configure its behavior and provide access to sensitive data. Think of them as a set of instructions and secrets you pass to your n8n an instance without writing them directly into your workflows or UI.

In the context of n8n, they fall into two main categories:

• Configuration Variables: These define how your n8n instance runs. You can set the host and port, define the public-facing webhook URL, configure the database connection, set timezones, and much more.
• Credential Variables: This is the most critical use case for security. Instead of pasting an API key directly into a credential field in the n8n UI, you can store it as an environment variable and reference it by name. This prevents sensitive data from being saved in your workflow JSON files.

Why Use Environment Variables in n8n?

While you can run a basic n8n instance without touching environment variables, using them is a non-negotiable best practice for any serious or production use case. Here's why:

• Enhanced Security: This is the biggest benefit. Storing API keys, database passwords, and other secrets as environment variables prevents them from being accidentally exposed in your workflow files, version control (like Git), or database backups.
• Configuration Flexibility: Easily change your instance's settings without modifying any core files. You can switch from a SQLite database to PostgreSQL or change your public domain by simply updating a variable and restarting the instance.
• Portability: Your workflows become more portable. Since credentials are not hard-coded, you can share a workflow with a colleague or move your instance to a new server without having to manually edit and replace every single credential.
• Simplified Management: For complex deployments, having a single file (like docker-compose.yml) that defines all your configuration makes management much easier than tweaking settings in a UI.

How to Set n8n Environment Variables

The most common way to self-host n8n is with Docker. The primary method for defining environment variables in a Docker setup is through a docker-compose.yml file. This file describes the services, networks, and volumes for your n8n application.

Here’s a basic example of how to add variables to your docker-compose.yml:

version: '3.7'

services:
  n8n:
    image: n8nio/n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=your.domain.com
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://your.domain.com/
      - GENERIC_TIMEZONE=Europe/Berlin
      - MY_CUSTOM_API_KEY=secret-api-key-value
    volumes:
      - ./n8n_data:/home/node/.n8n

In this example, everything under the environment: key is an environment variable.

1. Locate your docker-compose.yml file: This is the file you use to start n8n with the docker-compose up -d command.
2. Edit the file: Open it in a text editor.
3. Add your variables: Under the environment: section for the n8n service, add a new line for each variable using the format - VARIABLE_NAME=variable_value.
4. Save and restart: Save the file and then restart your n8n container for the changes to take effect: docker-compose up -d --force-recreate.

Common n8n Configuration Variables

While there are hundreds of variables you can use, a few are essential for most self-hosted setups. These variables ensure your n8n instance is accessible and functions correctly.

• N8N_HOST: The domain name your n8n editor UI is running on (e.g., n8n.mycompany.com). This is crucial for CORS (Cross-Origin Resource Sharing) to work correctly.
• N8N_PROTOCOL: Set this to https if you are using SSL encryption (which you always should).
• WEBHOOK_URL: The public-facing URL for your webhooks. This must be the full, accessible URL that external services will use to send data to n8n (e.g., https://n8n.mycompany.com/).
• GENERIC_TIMEZONE: Sets the server's timezone to ensure cron nodes and date-based operations run at the correct times. Find your timezone in the tz database list.
• Database Variables: If you're using PostgreSQL or MySQL instead of the default SQLite, you’ll need to set variables like DB_TYPE, DB_POSTGRESDB_HOST, DB_POSTGRESDB_USER, DB_POSTGRESDB_PASSWORD, and DB_POSTGRESDB_DATABASE.

Using Variables for Credentials and in Workflows

The primary security function of n8n environment variables is to manage secrets. Instead of pasting an API key into a credential field, you can reference a variable.

Let's say you defined - MY_STRIPE_API_KEY=sk_live_12345... in your docker-compose.yml.

Referencing in Credentials:

1. Go to the credentials section in n8n and create a new Stripe credential.
2. In the "API Key" field, instead of pasting the key, enter the following expression: ={{$env["MY_STRIPE_API_KEY"]}}
3. Save the credential.

Now, n8n will fetch the API key from the environment variable at runtime. The key itself is never stored in the n8n database or workflow JSON.

Referencing in Workflow Nodes:

You can also use these variables directly in your workflow expressions. For example, if you need to pass a custom header in an HTTP Request node, you could set its value to ={{$env["MY_CUSTOM_API_KEY"]}}. This is useful for values that aren't credentials but still change between environments (dev, staging, production).

Troubleshooting Common Issues

If your environment variables aren't working as expected, here are a few things to check:

• Container Not Restarted: The most common issue. You must restart your n8n container after changing your docker-compose.yml file. Use docker-compose up -d --force-recreate.
• Incorrect Syntax: Check your docker-compose.yml for syntax errors. YAML is sensitive to indentation. Ensure there are no stray tabs and that the alignment is correct.
• Wrong Variable Name: Double-check that the variable name in your expression (e.g., $env["MY_VAR_NAME"]) exactly matches the name you defined in your environment file.
• Forgetting the $env Object: In expressions, you must access variables through the $env object. Simply writing MY_VAR_NAME will not work.

The No-Fuss Alternative: Managed n8n Hosting

Managing YAML files, Docker containers, and command-line interfaces can be powerful, but it's also time-consuming and error-prone. It's frustrating to spend hours debugging a configuration issue when you'd rather be building automations.

This is where a managed solution like n8nautomation.cloud comes in. We handle all the complex backend setup for you:

• Secure Credential Management: A simple, secure UI for all your credentials. No need to touch environment files.
• Instant Setup: Your dedicated n8n instance is live in minutes, correctly configured with HTTPS and a custom domain.
- Automatic Updates & Backups: We manage server maintenance, security patches, and daily backups of your workflows and credentials.
• 24/7 Uptime: Forget about server crashes or memory issues. Our platform is built for reliability.

If you want to focus on building powerful automations without the headache of server administration, give n8nautomation.cloud a try. Plans start at just $7/month for a dedicated instance.