Quais São as Formas de Converter JSON para CSV Localmente? 6 Métodos, Comparados (Guia 2026)

As seis formas em resumo

Antes dos detalhes, aqui está todo o campo em uma só passada, porque a maneira mais rápida de escolher é eliminar cinco opções. Forma 1, a página de conversor que roda no navegador, não precisa de nada instalado e mantém o arquivo na sua máquina, mas você repete os cliques para cada arquivo. Forma 2, Python apenas com a biblioteca padrão, precisa do Python 3 e de nada mais, lida perfeitamente com dados simples e deixa valores aninhados como texto de representação do Python. Forma 3, Python com pandas, achata objetos aninhados em colunas com notação de pontos de forma automática, mas precisa do pandas instalado e ainda precisa de uma correção de uma linha para listas. Forma 4, jq, é uma única linha de terminal para dados simples e falha de forma barulhenta, em vez de falha errada, em dados aninhados. Forma 5, um script Node, achata objetos aninhados e junta listas com um auxiliar que você consegue ler por completo, e se encaixa de forma natural em um projeto. Forma 6, VS Code ou Excel, não precisa de nenhuma instalação nova se você já usa a ferramenta, e troca controle por conveniência.

Duas perguntas eliminam a maior parte da lista antes de você continuar lendo. Primeira, o seu dado é simples ou aninhado? Dados simples, um nível de chaves por objeto, funcionam com as seis formas. Dados aninhados, objetos dentro de objetos ou listas dentro de objetos, eliminam o comando jq simples e o script simples da biblioteca padrão do Python, a não ser que você some achatamento. Segunda, você vai fazer isso de novo? Uma conversão única favorece a página ou a ferramenta que você já tem. Uma exportação semanal favorece um script, porque o mesmo comando dá as mesmas colunas na mesma ordem toda vez. Guarde essas duas perguntas em mente e o restante do guia vira uma tabela de consulta.

Toda afirmação deste guia foi testada na mesma amostra antes da publicação: três pedidos, cada um com um id, um objeto cliente aninhado com nome e cidade, uma lista de marcadores e um total. Variantes simples do mesmo arquivo foram usadas onde um método só lida com dados simples. Quando um método falha em dados aninhados, este guia diz isso e mostra a falha exata em vez de disfarçar, porque uma falha que você consegue ver é mais segura do que uma tabela errada que você não consegue.

Forma 1: a página do conversor que roda no navegador

A forma local mais simples é o conversor desta página, e ela conta como local mesmo vivendo em um site. Quando você cola JSON ou envia um arquivo, a página interpreta o dado, achata o conteúdo e monta o texto CSV dentro da aba do seu navegador, e depois entrega o resultado como um arquivo baixado. Não existe etapa de envio nem servidor esperando pelo seu dado, porque o código de conversão vem junto com a página e roda na sua máquina. O único botão da página que toca na rede é o botão opcional de buscar por URL, que carrega JSON de um endereço da web que você digita. Cole ou envie o arquivo em vez de buscar por URL, e a rede nunca é usada.

Você pode verificar essa afirmação por conta própria em cerca de trinta segundos. Abra o conversor, desconecte da rede ou ligue o modo avião, e depois cole JSON e converta. O processo continua funcionando, porque nada da conversão precisa da rede. Vale a pena fazer esse teste uma vez, porque uma afirmação de privacidade vale mais quando é verificada do que quando é apenas confiada, e esta passa no teste.

A página é a forma certa para um arquivo único, para uma máquina onde você não pode instalar nada e para um arquivo que você quer converter antes de se comprometer com um script. Os limites dela são os mesmos de qualquer página: você repete os cliques para cada arquivo, e um arquivo muito grande vai deixar a aba lenta. Ela também decide algumas coisas por você, como a ordem das colunas e o comportamento de achatamento, por meio das opções dela em vez de código que você controla. Para um único arquivo, esses limites não importam. Para uma exportação semanal, escolha um script abaixo e guarde a página como sua verificação rápida.

Forma 2: Python apenas com a biblioteca padrão

Python é a forma local mais útil para a maioria das pessoas, porque já está instalado na maioria das máquinas de desenvolvedores e a biblioteca padrão sozinha já basta. Sem pandas, sem pacotes, nada para baixar. O script abaixo lê um arquivo JSON de objetos, pega os nomes das colunas do primeiro objeto e escreve um CSV com o módulo csv padrão, que cuida das aspas corretamente por conta própria. Salve como json2csv.py e rode com python3 json2csv.py orders.json orders.csv.

import json, csv, sys

with open(sys.argv[1]) as f:
    rows = json.load(f)

with open(sys.argv[2], 'w', newline='') as f:
    writer = csv.DictWriter(f, fieldnames=rows[0].keys())
    writer.writeheader()
    writer.writerows(rows)

Testado na amostra de três pedidos, este script produziu uma linha de cabeçalho mais três linhas de dados, e o resultado mostra o seu único limite honesto à vista. O objeto cliente aninhado saiu como uma string de representação do Python, algo como {'name': 'Ana', 'city': 'Lima'}, e a lista de marcadores saiu como uma lista de representação, algo como ['new', 'vip']. Um DictWriter simples não achata valores aninhados, então dados simples convertem de forma perfeita e dados aninhados convertem de forma visivelmente errada, o que pelo menos é fácil de notar. A correção é uma função recursiva curta que transforma objetos aninhados em chaves com notação de pontos, customer.name e customer.city, antes de escrever, e isso é exatamente o que o script Node da Forma 5 faz.

O módulo csv está fazendo um trabalho real por você aqui. Ele coloca aspas em células que contêm o delimitador, duplica aspas internas e escreve as quebras de linha que a sua planilha espera. Não monte CSV juntando valores com vírgulas por conta própria. A junção manual quebra na primeira vírgula dentro de um valor, e essa quebra é silenciosa: o arquivo parece certo até uma coluna se deslocar. A versão da biblioteca padrão também roda igual em toda máquina com Python 3, e é por isso que ela é o método a buscar quando um colega também precisa rodar a sua conversão.

Forma 3: Python com pandas json_normalize

Se a Forma 2 é o mínimo honesto, a Forma 3 é a melhoria que a maioria das pessoas realmente quer. A função json_normalize do pandas pega objetos aninhados e os transforma em colunas com notação de pontos de forma automática, então customer vira customer.name e customer.city sem nenhum auxiliar que você precise escrever. O script abaixo lê o mesmo arquivo de pedidos, normaliza o conteúdo e escreve um CSV. Ele precisa do pandas instalado, o que é uma única instalação, e depois o trabalho inteiro tem três linhas.

import json, pandas as pd

with open('orders.json') as f:
    rows = json.load(f)

df = pd.json_normalize(rows)
df.to_csv('orders.csv', index=False)

Testado na mesma amostra de três pedidos, json_normalize produziu as colunas id, tags, total, customer.name e customer.city, com três linhas. Esse é o comportamento a esperar: objetos aninhados achatam, campos simples passam direto e as colunas aninhadas achatadas vêm depois das simples. Listas são o detalhe que resta. A lista de marcadores saiu como texto de representação do Python, assim como na Forma 2, porque json_normalize não adivinha o que uma lista significa. A correção de uma linha é juntar listas curtas antes de escrever, por exemplo df['tags'] = df['tags'].apply(lambda v: '; '.join(v) if isinstance(v, list) else v), o que transforma a lista em uma célula legível. Para uma lista onde cada item deveria virar a sua própria linha, isso é uma operação diferente, explodir, e o pandas tem uma etapa explode separada para isso. A regra é simples: achatamento cuida de objetos, junção cuida de listas curtas, explosão cuida de listas que significam linhas.

O pandas é a forma certa quando o seu dado é aninhado, quando você vai limpar ou filtrar o conteúdo antes de escrever e quando você já trabalha em Python. Ele é a forma errada quando instalar um pacote não é possível, ou quando o trabalho é um único arquivo simples que jq ou a página terminariam mais rápido. A instalação é o único custo real, e ela se paga na segunda vez que você converte.

Forma 4: jq, o comando de uma linha para dados simples

Se você já usa o terminal, jq transforma o trabalho inteiro em uma linha, para dados simples. Ele lê JSON, pega as chaves do primeiro objeto como cabeçalho e depois emite cada linha como uma linha CSV, com as aspas cuidadas pelo formatador @csv. Nenhum arquivo de script, nenhum laço, nenhuma aspa manual. O comando abaixo lê um arquivo simples de pedidos, id, cidade e total por pedido, e escreve orders.csv. Note o limite, dito de forma clara: o formatador @csv rejeita objetos aninhados e listas, então este comando de uma linha é apenas para exportações simples, e a amostra aninhada das seções anteriores falha nele com um erro em vez de uma tabela errada, o que é o tipo seguro de falha.

jq -r '(.[0] | keys_unsorted) as $keys | $keys, map([.[ $keys[] ]])[] | @csv' orders-flat.json > orders.csv

Testado em um arquivo simples de três pedidos, a saída foi uma linha de cabeçalho entre aspas, "id","city","total", seguida por três linhas de dados com células de texto entre aspas e números sem aspas, exatamente a forma que @csv produz. O detalhe keys_unsorted importa: keys simples ordenaria as colunas em ordem alfabética, o que mudaria a ordem das colunas do seu arquivo. Se o seu dado tem objetos aninhados, jq precisa de um filtro de achatamento antes, e o comando de uma linha cresce até virar um pequeno script. Para exportações simples, que é o que a maioria das respostas de lista de API já são depois de desembrulhadas, o comando de uma linha é o trabalho inteiro, e ele roda sem rede em qualquer máquina com jq instalado.

Um cuidado: jq lê o arquivo inteiro na memória, então uma exportação de vários gigabytes vai forçar o processo assim como força uma aba do navegador. Para exportações comuns, até dezenas de megabytes, o processo é instantâneo. Para arquivos muito grandes, divida o arquivo antes ou use uma ferramenta de streaming, e trate isso como um problema separado da conversão.

Forma 5: Node, para quando a conversão vive dentro de um projeto

Node é a forma local certa quando a conversão faz parte de um projeto em vez de uma tarefa única: uma etapa de build, um pipeline de dados, um script que a equipe já roda. Node já vem com interpretação de JSON embutida, então o único trabalho é transformar linhas em texto CSV, e o pequeno script abaixo faz isso com um auxiliar de achatamento por pontos para que objetos aninhados virem colunas com notação de pontos, igual ao comportamento da página do conversor. Salve como json2csv.mjs e rode com node json2csv.mjs orders.json orders.csv.

import { readFileSync, writeFileSync } from 'node:fs';

const flatten = (obj, prefix = '', out = {}) => {
  for (const [k, v] of Object.entries(obj)) {
    const key = prefix ? prefix + '.' + k : k;
    if (v && typeof v === 'object' && !Array.isArray(v)) flatten(v, key, out);
    else out[key] = Array.isArray(v) ? v.join('; ') : v;
  }
  return out;
};

const rows = JSON.parse(readFileSync(process.argv[2], 'utf8')).map(r => flatten(r));
const cols = [...new Set(rows.flatMap(r => Object.keys(r)))];
const esc = v => v == null ? '' : /[",\n]/.test(String(v)) ? '"' + String(v).replaceAll('"', '""') + '"' : String(v);
const lines = [cols.join(','), ...rows.map(r => cols.map(c => esc(r[c])).join(','))];
writeFileSync(process.argv[3], lines.join('\n'));

Testado na mesma amostra, o script produziu o cabeçalho id,customer.name,customer.city,tags,total e três linhas, com o objeto cliente aninhado achatado em duas colunas e a lista de marcadores juntada com ponto e vírgula e espaço. A função de escape segue a mesma regra que a página do conversor usa: colocar aspas em uma célula apenas quando ela contém o delimitador, uma aspa ou uma quebra de linha, e duplicar qualquer aspa interna. Essa regra é todo o conteúdo das aspas em CSV, e acertar isso é a diferença entre um arquivo que abre de forma limpa e um arquivo que desloca colunas em silêncio.

O script é curto de propósito para que você consiga ler antes de rodar. Ele pega a união de todas as colunas entre as linhas, então uma linha sem um campo ganha uma célula vazia, o que combina com a página do conversor. Se você precisa de streaming para arquivos enormes, ou de renomear colunas, essas são adições a este script, não substituições dele.

Forma 6: as ferramentas que você já tem, VS Code e Excel

Mais duas formas locais não precisam de nenhuma instalação nova se você já usa as ferramentas. No VS Code, uma extensão converte o arquivo JSON aberto para CSV a partir da paleta de comandos, o que é o caminho local mais rápido quando você já está editando o arquivo. O passo a passo completo, incluindo qual extensão e os comandos exatos, está no guia do VS Code linkado abaixo. No Excel, o Power Query lê um arquivo JSON do seu disco e o transforma em uma tabela sem o arquivo jamais sair da sua máquina: Dados, Obter Dados, De Arquivo, De JSON, e depois expanda as colunas e carregue. Ambos funcionam totalmente sem rede depois que a ferramenta está instalada, e ambos mantêm o arquivo na sua máquina o tempo todo.

Essas formas trocam controle por conveniência. VS Code e Excel decidem o tratamento das colunas por você, e os padrões deles costumam ser bons para dados simples e às vezes surpreendentes para dados aninhados. Se a saída parecer errada, o diagnóstico é o mesmo de todos os outros casos: verifique se valores aninhados foram achatados ou deixados como texto JSON, e verifique o delimitador na abertura. Para um arquivo que você converte uma vez, qualquer uma das duas vence instalar algo novo. Para um arquivo que você converte toda semana, um script seu vence as duas, porque o script não depende de uma versão de extensão nem de uma janela que você precisa clicar de novo.

Existe mais uma nota honesta sobre a Forma 6. Excel e VS Code são locais, mas não são mínimos: são programas grandes com as suas próprias configurações, e uma configuração pode mudar o resultado, por exemplo um local que espera ponto e vírgula em vez de vírgula. Se a saída difere entre duas máquinas, verifique as configurações da ferramenta antes de culpar o dado. Scripts não têm esse problema, porque o script é a configuração.

Lado a lado: qual forma para qual situação

Com as seis formas testadas, a escolha vira uma lista curta de decisões. Arquivo único, nada para instalar, privacidade importa: a página do conversor. Arquivo simples, você vive no terminal, você quer um comando: jq. Arquivo simples ou aninhado, você já usa Python, você pode repetir o trabalho: Python com pandas. Nenhum pacote permitido, ou um colega também precisa rodar: Python da biblioteca padrão mais um auxiliar de achatamento para dados aninhados. Conversão dentro de um projeto ou de uma etapa de build: o script Node. Já editando o arquivo, ou já em uma planilha: VS Code ou Excel.

Duas situações merecem uma resposta direta porque aparecem o tempo todo. Dados sensíveis, onde o arquivo precisa ficar na máquina: qualquer forma desta página serve, mas um script curto que você mesmo lê é a opção mais forte, porque não há nada escondido para confiar. Leia o script antes de rodar em dados sensíveis, guarde o JSON original e prefira a página ou um script a qualquer ferramenta que envie o arquivo. Exportações semanais, onde a mesma forma chega de novo e de novo: um script, Python com pandas ou Node, porque o mesmo comando dá as mesmas colunas toda vez, e o script pode ser agendado.

E duas situações onde nenhuma forma desta página é a resposta certa. Várias pessoas precisam da mesma conversão com as mesmas configurações: uma página compartilhada vence cinco cópias de um script que divergem com o tempo. Um arquivo maior que a memória: toda forma aqui força o limite, e a correção é dividir o arquivo ou processar linha por linha, o que é um trabalho diferente da conversão. Nomear esses limites faz parte da comparação, não é uma falha dela.

O que todas as formas perdem, e por que você deve guardar o original

Toda forma desta página perde a mesma informação, porque a perda está na mudança de formato, não na ferramenta. Tipos viram texto: um número, um valor verdadeiro ou falso e um nulo viram caracteres em uma célula, e uma planilha pode reinterpretar esses valores na abertura. Objetos aninhados viram colunas com notação de pontos ou células juntadas, e listas viram texto juntado ou linhas extras, dependendo da forma que você escolheu. Não existe caminho de volta para a árvore original apenas a partir do CSV, porque o CSV não registra quais colunas eram aninhadas, quais células eram listas ou quais valores eram números.

É por isso que a primeira regra da conversão local é guardar o JSON original. Nunca converta por cima sobrescrevendo a fonte. Dê ao arquivo de saída um nome que ordene bem, por exemplo orders-2026-10-26.csv, e guarde o JSON ao lado dele. Se o CSV sair errado, você gera de novo a partir do JSON em vez de depurar um arquivo que já perdeu informação. Essa regra não custa nada e evita a única falha que você não consegue desfazer.

A segunda regra é contar as linhas. O CSV deve ter uma linha de cabeçalho mais uma linha por objeto no JSON, e uma contagem rápida pega a falha mais comum, que é um localizador de linhas escolher a lista errada de uma resposta embrulhada. Se as contagens não batem, aponte a ferramenta para a lista em si, ou desembrulhe a resposta antes, antes de confiar em qualquer linha.

Solução de problemas nas seis formas

Os mesmos quatro problemas aparecem em toda forma, e cada um tem uma correção. Uma abertura em uma só coluna significa uma incompatibilidade de delimitador no lado da abertura, não dado quebrado: importe de novo e escolha o delimitador com o qual o arquivo foi escrito. Dados aninhados aparecendo como texto de representação ilegível ou texto JSON em células significa que o achatamento foi pulado: o script simples do Python e o comando jq de uma linha não achatam, então use a versão pandas, o script Node ou a página com o interruptor de achatamento ligado.

Colunas em uma ordem diferente da do arquivo significa que uma ferramenta ordenou as chaves: jq precisa de keys_unsorted, e o script Node preserva a ordem da primeira aparição. Linhas faltando por completo significa que o localizador de linhas escolheu uma lista diferente da que você queria, o que acontece com respostas de API embrulhadas: a página do conversor tem uma etapa de detecção de linhas, e um script precisa da lista passada de forma explícita. Arquivo não encontrado significa que o terminal está em uma pasta diferente da do arquivo; verifique o caminho antes de qualquer outra coisa. JSON inválido significa que o arquivo fonte está quebrado perto da posição informada, geralmente uma aspa faltando ou uma vírgula no fim; valide o conteúdo e corrija a fonte, porque nenhum conversor deve adivinhar uma entrada quebrada.

Guias relacionados

• Convert JSON to CSV Locally: mantenha o arquivo na sua máquina (Guia 2026) →
• json to csv converter download: o que você realmente deveria baixar (Guia 2026) →
• Como Converter JSON Aninhado para CSV: O Que a Opção de Achatamento Realmente Faz (Guia 2026) →
• CSV abre em uma única coluna no Excel: por que acontece e como corrigir (Guia 2026) →
• Por que seu CSV mostra caracteres estranhos no Excel e como corrigir a codificação (Guia 2026) →
• Por que o Excel apaga os zeros à esquerda dos seus códigos em CSV e como mantê-los (Guia 2026) →
• Por que o Excel altera as datas do seu CSV e como mantê-las (Guia 2026) →
• Por que salvar seu CSV no Excel muda o arquivo e como manter o original seguro (Guia 2026) →
• CSV muito grande para o Excel: por que ele não abre e o que fazer (Guia 2026) →

Perguntas frequentes