Variáveis de ambiente n8n: como configurar no Docker

Aprenda a configurar as variáveis de ambiente do n8n no Docker: onde definir, como aplicar a mudança, as principais variáveis e a diferença para o recurso Variables.

Por Redação Eleven Host · @robson.direitodigital · 31 de outubro de 2026 · 9 min de leitura

As variáveis de ambiente n8n são configurações passadas ao container do n8n que mudam o comportamento da instância, como o fuso horário, o endereço público e a limpeza de execuções antigas. Elas entram na hora de criar o container, não pela tela do n8n.

Este guia mostra onde definir as variáveis no Docker, o que fazer depois de mudar uma, as variáveis que a documentação do n8n descreve para fuso, endereço, chave de criptografia, limpeza e logs, como lê-las dentro de um fluxo com $env e a diferença entre elas e o recurso Variables. Os nomes dos exemplos são fictícios.

Onde as variáveis de ambiente entram

Segundo a documentação do n8n sobre métodos de configuração, há três formas de passar uma variável quando o n8n roda em Docker. A primeira é a opção -e do docker run. A segunda, para quem usa Docker Compose, é o elemento environment: dentro de n8n: no arquivo docker-compose.yaml. A terceira é o sufixo _FILE, que cabe a variáveis individuais e permite guardar o valor num arquivo separado. A documentação indica o _FILE para segredos, como os do Docker e do Kubernetes.

Com docker run

O exemplo da documentação de instalação com Docker passa o fuso horário com -e. Aqui o valor America/Sao_Paulo ocupa o lugar do marcador que a página usa:

docker volume create n8n_data

docker run -it --rm \

--name n8n \

-p 5678:5678 \

-e GENERIC_TIMEZONE="America/Sao_Paulo" \

-e TZ="America/Sao_Paulo" \

-e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \

-v n8n_data:/home/node/.n8n \

n8nio/n8n

A barra invertida no fim de uma linha indica que o comando continua na linha de baixo. A própria página da documentação se marca como desatualizada e recomenda o Docker Compose, então vale ler este exemplo como ilustração do -e.

Com Docker Compose

No Compose, as variáveis ficam em environment:, em formato de lista ou de mapa. A documentação do Docker também aceita env_file:, que aponta para um arquivo com as variáveis. Este arquivo é um exemplo montado com as opções documentadas, e o n8n.env é fictício:

services:

n8n:

image: n8nio/n8n

restart: unless-stopped

ports:

- "5678:5678"

environment:

- GENERIC_TIMEZONE=America/Sao_Paulo

- TZ=America/Sao_Paulo

- N8N_HOST=n8n.example.com

- N8N_PROTOCOL=https

- N8N_WEBHOOK_URL=https://n8n.example.com/

- N8N_PROXY_HOPS=1

env_file:

- ./n8n.env

volumes:

- n8n_data:/home/node/.n8n

volumes:

n8n_data:

No n8n.env você poderia guardar valores mais sensíveis, como a chave de criptografia que aparece adiante. O guia de Docker Compose: como usar na VPS, passo a passo cobre o uso do Compose no dia a dia.

Depois de mudar uma variável: recrie o container

Para a mudança valer, o container precisa ser recriado. A documentação do Docker diz que o docker compose up "picks up the changes by stopping and recreating the containers", isto é, o Compose aplica a mudança parando e recriando o container.

Com docker run, o roteiro é o mesmo da atualização do n8n na documentação: parar, remover e rodar de novo, agora com o -e novo. Pelo nome do exemplo acima, fica assim:

docker stop n8n

docker rm n8n

Depois disso, repita o docker run com a variável nova. Nos exemplos, os dados ficam no volume n8n_data, montado em /home/node/.n8n. Essa pasta guarda o arquivo do banco e a chave de criptografia, segundo a documentação.

Por isso este guia segue o roteiro de recriar o container, e não só reiniciá-lo.

Quer conhecer o n8n da Eleven Host? O n8n Essencial sai a partir de R$ 19,90/mês; confira na loja o que cada plano inclui. Ver planos de n8n

Variáveis principais

A lista abaixo reúne as variáveis que a documentação descreve nas páginas de fuso, implantação, execuções e logs. Os padrões são os da documentação.

Fuso horário

• GENERIC_TIMEZONE: o fuso da instância n8n, importante para nós de agendamento como o Cron. O padrão é America/New_York.
• TZ: define o fuso do sistema dentro do container e controla o que scripts e comandos como date retornam. Ela aparece no guia de instalação com Docker, não na página de fuso.

Use as duas com o mesmo fuso, como no exemplo. Para os fluxos agendados, o guia de agendar fluxo no n8n com o Schedule Trigger mostra o gatilho que depende desse horário.

Endereço, porta e protocolo

• N8N_HOST: o nome do host em que o n8n roda. O padrão é localhost.
• N8N_PORT: a porta HTTP do n8n. O padrão é 5678.
• N8N_PROTOCOL: http ou https. O padrão é http.
• N8N_EDITOR_BASE_URL: a URL pública em que as pessoas acessam o editor. Não tem padrão.
• N8N_PROXY_HOPS: quantos proxies reversos existem na frente do n8n. O padrão é 0, e a documentação manda usar 1 atrás de um proxy reverso.

URL dos webhooks

A N8N_WEBHOOK_URL é o nome atual da variável que informa a URL pública dos webhooks, por exemplo N8N_WEBHOOK_URL=https://n8n.example.com/. A documentação a indica atrás de um proxy, porque o n8n roda por dentro na porta 5678 e o proxy reverso o expõe na internet pela porta 443. O nome antigo, WEBHOOK_URL, está obsoleto desde a versão 2.35.0. Ela ainda funciona, mas gera um aviso no log, então troque pelo nome novo.

Chave de criptografia

A N8N_ENCRYPTION_KEY é a chave usada para criptografar as credenciais no banco do n8n. Se você não definir uma, o n8n gera uma chave aleatória na primeira execução, e ela fica na pasta de dados, a .n8n. Guarde essa chave em lugar seguro, porque ela é a chave das credenciais gravadas no banco.

Limpeza de execuções

• EXECUTIONS_DATA_PRUNE: liga ou desliga a exclusão contínua dos dados de execuções passadas. O padrão é true.
• EXECUTIONS_DATA_MAX_AGE: a idade, em horas, que uma execução precisa ter para ser apagada. O padrão é 336 horas, ou seja, 14 dias.
• EXECUTIONS_DATA_PRUNE_MAX_COUNT: o limite de execuções guardadas. O padrão é 10000, e 0 significa sem limite.

Logs e banco de dados

O N8N_LOG_LEVEL aceita info, warn, error ou debug, e o padrão é info. A N8N_LOG_OUTPUT escolhe entre console e file, com padrão console.

A DB_TYPE indica o banco do próprio n8n: sqlite, que é o padrão, ou postgresdb. Para Postgres existem variáveis como DB_POSTGRESDB_HOST e DB_POSTGRESDB_PORT, entre outras. Pela página de mudanças da versão 2.0, o suporte a MySQL e MariaDB como banco do n8n foi removido, mas o nó MySQL continua. Para ligar um fluxo a um banco MySQL, veja n8n com MySQL: como conectar e gravar dados no banco.

Ler uma variável dentro de um fluxo com $env

Dentro de uma expressão, o objeto $env dá acesso às variáveis de ambiente de configuração da instância. A documentação o descreve como o objeto que contém as variáveis de ambiente de configuração da instância n8n. Em uma expressão, o uso fica assim:

{{ $env.NOME_DA_VARIAVEL }}

Mas há um bloqueio. A variável N8N_BLOCK_ENV_ACCESS_IN_NODE controla se os usuários podem acessar variáveis de ambiente em expressões e no nó Code. Com o valor true, o acesso fica bloqueado, e com false, liberado. Segundo a página de mudanças da versão 2.0, o padrão passou a ser true nessa versão. Quem escreve $env num fluxo do n8n 2.x e não recebe o valor pode conferir essa variável.

Para voltar a ler as variáveis nos fluxos, a documentação manda definir N8N_BLOCK_ENV_ACCESS_IN_NODE=false.

Variáveis de ambiente e o recurso Variables são coisas diferentes

O n8n também tem um recurso chamado Variables, que não é a mesma coisa. A documentação diz que as variáveis personalizadas permitem guardar e reutilizar valores em fluxos, e o acesso é por $vars.<nome-da-variavel>. O valor de cada uma é texto. Elas são somente leitura nos fluxos, e o valor só muda pela interface.

Segundo a mesma página, o recurso está nos planos n8n Cloud Pro e Enterprise, e no self-hosted nos planos Business e Enterprise. Só o dono ou o administrador cria variáveis. Quem usa a versão gratuita self-hosted não tem o Variables, e por lá só existe o $env. O escopo pode ser global, para toda a instância, ou por projeto, a partir da versão 1.118.0.

Resumindo: a variável de ambiente é definida no container ($env), e a do recurso Variables é criada na interface ($vars).

Outras mudanças da versão 2.0 que mexem com variáveis

A página de mudanças da 2.0 lista mais pontos que tocam configuração. A N8N_CONFIG_FILES foi removida, e no lugar dela se usam variáveis de ambiente, um arquivo .env ou o _FILE. A biblioteca dotenv foi atualizada, e isso muda a leitura do .env: crases pedem aspas e um # no início da linha é comentário. O arquivo de configuração passa a exigir a permissão 0600, controlada pela N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS.

Está avaliando um lugar para os seus fluxos do n8n? O n8n Essencial sai a partir de R$ 19,90/mês; confira na loja o que cada plano inclui. Conhecer o n8n Essencial

Perguntas frequentes

Como definir variáveis de ambiente no n8n com Docker?

Com a opção -e do docker run ou com environment: (e, se quiser, env_file:) no Docker Compose. Para segredos, a documentação indica o sufixo _FILE.

Preciso recriar o container depois de mudar uma variável?

Sim. O docker compose up percebe a mudança e recria o container. Com docker run, pare, remova e rode de novo com o -e novo.

Qual variável acerta o horário dos fluxos agendados?

A GENERIC_TIMEZONE, que a documentação indica para nós de agendamento. A TZ define o fuso do sistema no container. Use as duas com o mesmo fuso.

Meu $env não devolve o valor. O que pode ser?

No n8n 2.x, o padrão da N8N_BLOCK_ENV_ACCESS_IN_NODE passou a ser true, o que bloqueia o acesso às variáveis de ambiente em expressões e no nó Code. Defina false para voltar a ler.

O que é a WEBHOOK_URL que vejo em tutoriais antigos?

É o nome antigo da N8N_WEBHOOK_URL, obsoleto desde a versão 2.35.0. Ele ainda funciona, com um aviso no log.