n8n Environment Variables Explained: A Practical Guide

 

Environment variables control a significant part of how a self-hosted n8n instance behaves. The challenge is that the relevant settings are spread across different parts of the documentation, making it difficult to get a clear picture of which variables actually matter.

Here’s a practical breakdown of the most useful n8n environment variables and what each one is typically used for.

What Environment Variables Actually Do

An environment variable is essentially a configuration setting passed to the n8n application when it starts. These variables can control everything from database connections and webhook URLs to execution data and security settings, without requiring you to modify the application code itself.

For a self-hosted instance, environment variables are commonly defined in a .env file or directly in a Docker Compose configuration, depending on how you deploy n8n.

Most Useful n8n Environment Variables

N8N_HOST — Defines the hostname or domain where your n8n instance is accessible. This is important for generating webhook URLs correctly and should normally match the public domain you use to access n8n.

N8N_PROTOCOL — Defines the protocol used by your n8n instance. In a production setup using HTTPS, this is typically set to https.

WEBHOOK_URL — Lets you explicitly define the base URL used for webhooks. This is particularly useful when n8n is behind a reverse proxy or when the public URL differs from the internal hostname used by the server.

N8N_PAYLOAD_SIZE_MAX — Controls the maximum request payload size n8n will accept. This can become important when workflows receive large JSON payloads, files, or other sizeable requests.

EXECUTIONS_DATA_PRUNE — When enabled, n8n can automatically remove older execution data according to your retention settings. This helps prevent the execution database from growing unnecessarily over time.

EXECUTIONS_DATA_MAX_AGE — Works together with execution-data pruning to define how long execution data should be retained before it is removed. The value is specified in hours.

N8N_ENCRYPTION_KEY — One of the most important security-related settings. n8n uses this key to encrypt stored credentials. Keep the key safe and do not change it on an existing instance unless you understand the consequences, because changing it can make previously stored credentials inaccessible.

Setting Environment Variables — Docker Example

If you’re running n8n with Docker Compose, your configuration might look something like this:

environment:
  - N8N_HOST=automate.yourdomain.com
  - N8N_PROTOCOL=https
  - N8N_ENCRYPTION_KEY=your-secure-key-here
  - EXECUTIONS_DATA_PRUNE=true
  - EXECUTIONS_DATA_MAX_AGE=168

After modifying your environment variables, restart the n8n container so the changes take effect.

Common Mistakes to Avoid

Not setting N8N_ENCRYPTION_KEY explicitly — n8n can generate an encryption key automatically, but relying on an automatically generated key without properly persisting it can cause problems if the instance is recreated or the key changes. For a production deployment, store the key securely and make sure it persists across restarts and deployments.

Confusing N8N_HOST with the server’s IP address — N8N_HOST should normally represent the public hostname or domain through which users and external services access n8n, rather than an internal server IP address. Incorrect configuration can result in webhook URLs that do not match the address external services can actually reach.

Changing the encryption key on an existing instance — This is an easy mistake to make when moving or rebuilding a server. Before changing N8N_ENCRYPTION_KEY, make sure you understand how your existing credentials are encrypted and backed up.

Keeping execution data forever — If your instance runs a large number of workflows, execution history can grow quickly. Configure pruning and an appropriate retention period rather than allowing unnecessary historical data to accumulate indefinitely.

A Simple Configuration Checklist

• Public URL: Make sure N8N_HOST, N8N_PROTOCOL, and your webhook configuration match your actual deployment.
• Security: Set and securely store N8N_ENCRYPTION_KEY.
• Execution data: Enable pruning if you do not need to retain execution history indefinitely.
• Payloads: Increase N8N_PAYLOAD_SIZE_MAX only when your workflows genuinely need to accept larger requests.
• After changes: Restart the n8n container or application so the new environment variables are loaded.

Wrap-Up

You don’t need to memorize every n8n environment variable. A small set of settings covers many of the practical configuration issues you’ll encounter when running n8n yourself.

Start with the basics: your public hostname, HTTPS configuration, webhook URL, encryption key, execution-data retention, and payload limits. Once those are configured correctly, you can adjust additional variables as your deployment grows.

The most important rule is to treat environment variables as part of your deployment configuration. Keep them documented, back them up securely where appropriate, and be especially careful with security-sensitive settings such as N8N_ENCRYPTION_KEY.