Como atualizar o n8n sem quebrar seus fluxos: backup, Docker, npm e como voltar atrás

Fala aí, beleza?

Atualizar o n8n não é o problema

perder fluxo que já está rodando é

O n8n lança uma versão minor na maioria das semanas, então quem roda self-hosted (Docker ou npm) decide sozinho quando subir de versão

E se você tem um fluxo que integra o n8n com o Notion rodando todo dia, a dúvida deixa de ser técnica e vira medo mesmo: e se quebrar tudo?

Aqui a gente resolve isso em três frentes: backup dos workflows, o comando certo pra sua instalação (Docker, Compose, Docker Desktop ou npm) e o caminho de volta quando a versão nova apronta 🙂

Antes de atualizar: o que checar na sua instalação

Antes de tocar em qualquer tag de imagem, para um minuto e confere estes pontos

É chato? é

Mas é o que separa "subi de versão" de "perdi o banco"

• Saiba qual é o seu método de instalação: Docker puro, Docker Compose, Docker Desktop ou npm. O comando muda pra cada um, e rodar o comando do vizinho é a forma mais rápida de se enrolar
• Volume persistente montado: no Docker, o volume n8n_data fica montado em /home/node/.n8n. Sem volume persistido e montado ao parar e iniciar o contêiner, todos os dados vão embora
• Onde mora o seu banco: o arquivo SQLite padrão fica em ~/.n8n/database.sqlite
• A chave de criptografia: ela vive nesse mesmo diretório, junto com os logs da instância e os assets do source control. É por isso que perder o diretório é MUITO pior do que perder o contêiner
• Versão do Node.js (só pra quem usa npm): o n8n instalado via npm exige Node.js entre 20.19 e 24.x, inclusive

Formação Recomendada

Formação Agentes de IA

Domine a criação de Agentes de IA e Venda para Empresas

• 402 aulas
• 32 projetos
• 38h 19min

Conhecer formação

Stable ou beta? (os antigos latest e next)

O n8n renomeou os canais de release: latest virou stable e next virou beta

As tags antigas continuam sendo publicadas por compatibilidade, tanto no npm quanto no Docker Hub, então você ainda vê as quatro por aí

A regra é simples: stable designa a última release estável e é a indicada pra produção, enquanto beta é a mais recente e pode ser instável

Se é a sua instância que atende cliente, você quer stable, sem romance

Passo 1: backup dos seus workflows (e das credenciais)

O n8n tem uma CLI de servidor embutida, que roda na mesma máquina da instalação e acessa o banco direto

E aqui vem a parte boa: a maioria dos comandos funciona com o n8n desligado

Ou seja, dá pra parar a instância e ainda assim tirar o backup, o que é exatamente o que você quer numa janela de manutenção

1. Exporte todos os workflows pela CLI

n8n export:workflow --all

2. Prefira a flag de backup, que já liga as opções certas

A flag --backup equivale a --all --pretty --separate, e --output define a pasta de destino:

n8n export:workflow --backup --output=backups/latest/

Com --separate, cada workflow é salvo como um arquivo JSON próprio, nomeado com o ID dele

Isso importa na hora de restaurar só um fluxo, em vez de um arquivão único com tudo dentro

3. Tem poucos fluxos? dá pra baixar pela interface

No editor, os três pontinhos no canto superior direito da barra de navegação têm a opção Download

É o caminho manual, serve bem pra quem tem 3 ou 4 workflows e não quer nem abrir terminal

4. Exporte as credenciais (com cuidado redobrado)

n8n export:credentials --decrypted

O --decrypted exporta as credenciais em texto plano, e ele existe pra um caso específico: migrar entre instalações com chave de criptografia diferente

Tome cuidado! toda informação sensível fica visível nos arquivos, então isso não vai pro Git, não vai pro Drive compartilhado, não vai pro grupo do WhatsApp

5. Quer o banco inteiro? use o export de entidades

n8n export:entities

Esse comando gera arquivos criptografados dentro de um diretório compactado

Do outro lado, o import:entities importa pra outro tipo de banco e espera o banco vazio (dá pra forçar com --truncateTables)

Os tipos suportados são SQLite e Postgres

O erro comum deste passo: achar que o JSON do workflow leva a credencial junto

Ele não leva

O JSON exportado inclui os nomes e os IDs das credenciais, e só. Os IDs não são sensíveis, mas os nomes podem ser, então vale remover ou anonimizar antes de compartilhar o arquivo com alguém

O segundo tropeço mora na volta: na importação, workflows e credenciais com os mesmos IDs no banco existente são sobrescritos

Se você não quer isso, apaga ou troca os IDs antes de importar

Passo 2: atualizar o n8n no Docker

Backup na mão? bora ver na prática

1. Baixe a imagem nova do registro oficial

docker pull docker.n8n.io/n8nio/n8n

2. Quer travar uma versão específica, em vez de pegar a estável do momento?

docker pull docker.n8n.io/n8nio/n8n:1.81.0

E se você quiser mesmo brincar com a instável, existe o canal next:

docker pull docker.n8n.io/n8nio/n8n:next

Esse aqui não é pra máquina de produção, combinado?

3. Pare o contêiner e inicie de novo

Esse é o ponto que MUITA gente pula: baixar a imagem não troca a versão em uso

Depois do pull, é preciso parar o contêiner e iniciar novamente pra versão nova entrar em uso

Se você deu pull e a interface continua igual, provavelmente é isso

4. Usa Docker Compose? são três comandos, na pasta do arquivo compose

docker compose pull
docker compose down
docker compose up -d

5. Usa Docker Desktop? é pelo menu de contexto

Vá na aba Images e escolha Pull no menu de contexto, depois pare e inicie o contêiner

Mesma lógica do terminal, só que no clique

O erro comum deste passo: subir o contêiner de novo sem o volume montado

O volume precisa ser persistido e montado ao parar e iniciar o contêiner, senão todos os dados são perdidos

Se você ainda não criou o seu, é assim:

docker volume create n8n_data

E ele entra na hora de subir com -v n8n_data:/home/node/.n8n

Lembra que é ali dentro que moram o banco, a chave de criptografia, os logs da instância e os assets do source control

Passo 3: atualizar o n8n instalado via npm

Quem instalou global segue por outro caminho, e ele é bem mais curto

1. Instalação global

npm install n8n -g

2. Travando uma versão específica

A sintaxe com @ serve tanto pra instalar quanto pra fixar a versão que você quer:

npm install [email protected]

Isso é útil quando você não quer a mais recente, e sim aquela versão que você já testou e sabe que roda com os seus fluxos

3. Confira o Node.js antes de qualquer coisa

O n8n via npm pede Node.js entre 20.19 e 24.x, inclusive

O erro comum deste passo: atualizar o n8n sem olhar a versão do Node e cair fora da faixa suportada

Aí a instalação até acontece e a instância não sobe, e você fica caçando problema no n8n quando o problema estava no ambiente

Saltos que quebram fluxo: o que mudou na v2 e o que vem na v3

O n8n usa versionamento semântico, no formato MAJOR.MINOR.PATCH

Traduzindo pra você ler o número da versão sozinho: MAJOR muda quando existe mudança incompatível, MINOR quando entra funcionalidade compatível e PATCH quando são correções

Ou seja: pular de minor é rotina, pular de MAJOR é dia de ler a documentação antes 😀

Estas são as breaking changes documentadas da v2.0:

E o que já está anunciado pra v3.0:

A v3.0 está programada pra outubro de 2026, e ela mexe justamente em quem está lendo este post

• O self-hosted passará a exigir deploy baseado em Docker, e as instalações via npm / npx n8n deixam de ser suportadas
• O Chat Hub é aposentado
• A importação de workflow por URL sai do editor

A própria documentação diz que a página será atualizada com detalhes e guias de migração conforme a v3 se aproxima, então dá pra acompanhar sem correria

Mas se hoje a sua instalação é npm, já sabe: o relógio está correndo

Ler a lista de breaking changes antes vale cada minuto, ainda mais se os seus fluxos misturam nós de código com automações com agentes de IA, que é onde a dependência de nó específico costuma ser maior

Como foi na prática atualizar para a v2

Aqui eu falo do que eu vi com o meu próprio ambiente, beleza?

Eu rodei as duas versões lado a lado: a v1 com os meus workflows em produção e a v2 em uma instância de teste separada, com o banco de dados resetado

A de teste era teste mesmo, eu não migrei a produção pra ela

E esse é o meu recado mais importante: não atualize o workflow que está em produção por impulso, porque pode dar problema

A primeira mudança que me pegou foi de interface: o botão de ativar e desativar não fica mais na lista de workflows

A ação passa a ser feita dentro do próprio workflow, via publicar e despublicar, e o despublicar virou uma ação manual dentro da tela de publicação

Parece bobagem, mas é o tipo de coisa que te faz perder cinco minutos procurando onde clicar

O que me deixou animado foi a velocidade

Na v1 apareceu aquele loader girando quando eu salvava, e na v2 o salvamento foi quase imediato

Eu testei adicionar o mesmo nó de memória simples nos dois ambientes pra comparar, e o modal demorava um instante pra abrir na v1 e abria de imediato na v2

Vale a ressalva honesta: o meu workflow era pequeno, e essa diferença tende a aparecer MUITO mais em workflows grandes

Na instância de teste eu também abri o histórico de versões do workflow, com as versões nomeadas, dava pra consultar e voltar pra uma versão anterior quando a nova apresenta erro

É parecido com um repositório de código, sabe? antes, salvando várias vezes por dia, os salvamentos ficavam todos embaralhados e sem nome

Outra coisa que me agradou: as configurações ficam acessíveis por um ícone de engrenagem, sem precisar sair pra uma página isolada como na versão anterior

A instalação em si eu fiz pelo painel que uso na VPS, trocando a tag da imagem do n8n pra apontar pra versão que eu queria testar

E antes de subir qualquer coisa eu li o artigo de breaking changes, pra saber o que afeta os workflows antigos

Se eu pudesse resumir a receita: leve os workflows pra uma máquina separada antes, veja o que quebra ali e vá se preparando com calma…

Vídeo: atualizando para a v2 passo a passo

Se você prefere executar acompanhando a tela, no vídeo abaixo eu mostro esse teste todo na prática, do comparativo entre as duas instâncias até a troca da imagem

Deu problema depois de atualizar: como voltar atrás

Atualizou, subiu, e alguma coisa não está certa

Calma, respira, e vai por sintoma:

E se a bronca for a versão em si, o caminho de volta tem três frentes

1. Volte pra imagem anterior no Docker

docker pull docker.n8n.io/n8nio/n8n:1.81.0

Depois é a mesma dança de sempre: parar o contêiner e iniciar de novo, senão a versão antiga não entra em uso

2. Reinstale a versão anterior no npm

npm install [email protected]

3. Reverta a migração de banco, quando for o caso

n8n db:revert

Esse comando reverte a migração de banco na versão atual

Pra reverter mais de uma migração, é preciso repetir o processo, uma por vez

4. Reimporte os workflows que você salvou lá no passo 1

Na interface você tem três caminhos: Import from File (JSON do computador), Import from URL (JSON de uma URL) e o velho copiar e colar de nós no editor, com Ctrl+C e Ctrl+V (cmd no Mac)

Lembrando do detalhe que já apareceu lá em cima: IDs iguais são sobrescritos no banco existente

O limite duro: nem toda versão tem volta

Aqui não tem jeitinho

Existe caso documentado de versão sem retorno: quem atualiza pra 0.234.0 não consegue voltar pra versão anterior, porque essa versão contém uma migração que muda os IDs de credenciais e workflows pra strings nanoId

É o exemplo perfeito de por que o backup vem ANTES do comando, e não depois do susto

Por isso a própria documentação recomenda backup completo do n8n em upgrades de versão significativos

No caso documentado da 0.x pra 1.x, a orientação era atualizar antes pra última release 0.x e só então dar o salto

Traduzindo pra rotina: sobe por degraus, testa em instância separada e só depois encosta na produção

Próximo passo: transforme o backup em rotina

Atualizar o n8n é seguro quando o backup é rotina, e vira roleta quando o backup é improviso de última hora

O comando é um só, ele roda até com a instância desligada, e o resultado é uma pasta com um JSON por workflow

Agenda isso, nem que seja num cron simples da própria máquina

E faz o que quase ninguém faz: testa a restauração antes de precisar dela

Sobe uma instância separada, importa os JSON, confere se os fluxos abrem certinho. Backup que nunca foi restaurado é só um arquivo bonito na pasta 😛

Com isso no lugar, o que vem pela frente fica bem menos assustador: a v3.0 está programada pra outubro de 2026 e vai exigir deploy baseado em Docker, com npm e npx n8n fora do jogo

Se você está no npm hoje, o próximo experimento da sua lista já tem nome: montar a mesma instância em Docker, com volume persistido, e ver os seus fluxos rodando lá

até o próximo post!