Convert JSON to CSV Locally: mantenha o arquivo na sua máquina (Guia 2026)

O que converter JSON para CSV localmente realmente significa?

A palavra localmente é usada para três coisas diferentes, e a diferença importa quando a privacidade é o motivo da sua pergunta. O primeiro significado é executado no cliente: uma página da web que faz a conversão dentro da sua aba do navegador. Você continua olhando para um site, mas a página nunca envia os seus dados para lugar nenhum, porque o código de conversão roda na sua máquina. O segundo significado é software instalado: um programa no seu computador, como um aplicativo de desktop ou uma extensão de editor, que lê um arquivo e grava um arquivo. O terceiro significado é um script que você mesmo executa: algumas linhas de Python, jq ou Node que você controla completamente e pode ler antes de executar.

Os três mantêm o arquivo na sua máquina. Eles diferem no que você precisa instalar, no que precisa aprender e em quão repetível é o resultado. Uma página executada no cliente não precisa de nada instalado e nada aprendido, mas você repete os cliques toda vez. Um script precisa de uma ferramenta instalada e de algumas linhas digitadas, mas você pode executá-lo em cem arquivos com um comando e obter o mesmo resultado toda vez. O restante deste guia trata os três como locais, e diz qual deles é cada método.

Uma coisa que localmente não significa é privado por mágica. Um script baixado de um desconhecido e executado sem leitura pode fazer qualquer coisa na sua máquina, incluindo enviar o seu arquivo para outro lugar. Os scripts deste guia são curtos o bastante para ler por completo, e você deveria ler qualquer script antes de executá-lo em dados sensíveis. Local é uma propriedade de onde o trabalho acontece, e você a verifica lendo o código ou observando a rede, não confiando em um rótulo.

Quando o local é a escolha certa, e quando não é

A conversão local é a escolha certa em quatro situações. A primeira é dados sensíveis: listas de clientes, registros internos, qualquer coisa sob um contrato ou uma regra de privacidade que diga que os dados ficam dentro da empresa. Se o arquivo não pode sair da máquina, um conversor do lado do servidor simplesmente não é uma opção, por mais conveniente que seja. A segunda é falta de conexão: um avião, um local remoto, uma rede que bloqueia a ferramenta que você queria. Ferramentas locais funcionam exatamente da mesma forma offline, porque não há servidor a alcançar.

A terceira é repetibilidade. Se você converte o mesmo tipo de exportação toda semana, um script transforma uma sessão de quinze minutos de cliques em um único comando, e o mesmo comando dá as mesmas colunas na mesma ordem toda vez. A quarta é tamanho e controle: um arquivo com milhões de linhas, ou um arquivo cujas colunas você precisa renomear e reordenar, é mais fácil de lidar com um script que você pode ajustar do que com uma página cujas opções são fixas.

O local é a escolha errada em três situações. Se várias pessoas precisam da mesma conversão e das mesmas configurações, uma página compartilhada vence cinco cópias de um script que se distanciam umas das outras. Se você não tem uma máquina que controla, por exemplo um computador emprestado ou um laptop de trabalho bloqueado que não pode instalar Python ou jq, uma página executada no cliente continua local e continua sendo a melhor escolha. E se o arquivo for maior do que a sua máquina consegue manter confortavelmente na memória, nenhum método local ajuda até você dividir o arquivo ou transmiti-lo em fluxo, o que é um trabalho diferente. Faça uma pergunta antes de escolher: este arquivo precisa ficar nesta máquina, e eu vou fazer isso de novo? Se as duas respostas forem sim, vá para o local e automatize com script. Se só a primeira for sim, uma página executada no cliente basta.

Método 1: o conversor desta página já é local

O método local mais simples já está na sua frente. O conversor desta página roda inteiramente dentro da sua aba do navegador. Quando você cola JSON ou envia um arquivo, a página analisa o conteúdo, achata o conteúdo e constrói o texto CSV no seu navegador, depois entrega o resultado como um arquivo baixado. Não há etapa de envio nem servidor esperando pelos seus dados, porque o código de conversão vem com a página e roda na sua máquina.

Você pode verificar essa afirmação em cerca de trinta segundos, e deveria, porque uma afirmação sobre privacidade vale a pena conferir. Abra o conversor, desconecte-se da rede ou ligue o modo avião, depois cole JSON e converta. Ele continua funcionando, porque nada na conversão precisa da rede. O único botão da página que toca a rede é o botão opcional de buscar a partir de URL, que carrega JSON de um endereço da web que você digita. Se você colar ou enviar em vez de buscar, a rede nunca é usada.

Isso faz da página o método local certo para conversões únicas e para máquinas onde você não pode instalar nada. Os limites são os mesmos de qualquer página: você repete os cliques para cada arquivo, e arquivos muito grandes vão deixar a aba lenta. Para um único arquivo, ou para um arquivo que você só converte uma vez, esses limites não importam. Para uma exportação semanal, passe para um script abaixo e mantenha a página como sua verificação rápida.

Método 2: Python, o cavalo de batalha local, sem pacotes

Python é o método local mais útil para a maioria das pessoas, porque já está instalado na maioria das máquinas de desenvolvedores e só a biblioteca padrão 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 grava um CSV com o módulo csv padrão, que trata as aspas corretamente por conta própria. Salve como json2csv.py e execute com python3 json2csv.py orders.json orders.csv.

Python, standard library only

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 no arquivo de exemplo usado ao longo deste guia, três pedidos com campos id, customer e tags, este script produziu uma linha de cabeçalho mais três linhas de dados. O objeto customer aninhado saiu como uma string repr do Python, não como texto JSON, e a lista tags saiu como uma lista repr, porque um DictWriter simples não achata valores aninhados. Esse é o limite honesto da versão curta: dados planos convertem perfeitamente, dados aninhados precisam de mais um passo. O passo de achatamento é pequeno. Uma função recursiva curta que transforma objetos aninhados em chaves com notação de ponto, customer.name e customer.city, antes de gravar, dá a você as mesmas colunas que a página do conversor produz com a opção de achatamento ligada.

O módulo csv está fazendo trabalho de verdade para você aqui. Ele coloca entre aspas as células que contêm o delimitador, duplica as aspas internas e grava as quebras de linha que a sua planilha espera. Não construa CSV unindo valores com vírgulas por conta própria. A junção feita à mão quebra na primeira vírgula dentro de um valor, e essa quebra é silenciosa: o arquivo parece bom até uma coluna se deslocar. A versão da biblioteca padrão também roda da mesma forma em toda máquina com Python 3, e é por isso que ela é o método a usar quando um colega também precisa executar a sua conversão.

Método 3: jq, o comando de uma linha para quem vive no terminal

Se você já usa o terminal, o jq transforma todo o trabalho em uma linha, para dados planos. Ele lê JSON, escolhe as chaves do primeiro objeto como cabeçalho, depois emite cada linha como uma linha CSV, com as aspas tratadas pelo formatador @csv. Sem arquivo de script, sem laço, sem aspas manuais. O comando abaixo lê um arquivo plano de pedidos, id, city e total por pedido, e grava orders.csv. Observe o limite, dito com clareza: o formatador @csv rejeita objetos e listas aninhados, então este comando de uma linha é só para exportações planas, e o exemplo aninhado da seção de Python falha nele com um erro em vez de uma tabela errada, o que é o tipo seguro de falha.

jq one-liner, flat objects

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

Testado em um arquivo plano 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 o @csv produz. O detalhe keys_unsorted importa: keys simples ordenariam as colunas alfabeticamente, o que mudaria a ordem das colunas em relação ao seu arquivo. Se os seus dados têm objetos aninhados, o jq precisa primeiro de um filtro de achatamento, e o comando de uma linha cresce até virar um script pequeno. Para exportações planas, que é o que a maioria das respostas de lista de API já é depois de desembrulhada, o comando de uma linha é todo o trabalho, e ele roda offline em qualquer máquina com jq instalado. O limite de dados aninhados foi confirmado na máquina de teste: o mesmo filtro no exemplo aninhado falha com um erro em vez de uma tabela errada, o que é o tipo seguro de falha.

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

Método 4: Node, para quando a conversão vive dentro de um projeto

Node é o método local certo 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á executa. Node já vem com análise de JSON embutida, então o único trabalho é transformar linhas em texto CSV, e o script pequeno abaixo faz isso com um auxiliar de achatamento por ponto, para que objetos aninhados virem colunas com notação de ponto, igual ao comportamento da página do conversor. Salve como json2csv.mjs e execute com node json2csv.mjs orders.json orders.csv.

Node script with dot-flattening

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 no mesmo exemplo, o script produziu o cabeçalho id,customer.name,customer.city,total e três linhas, com o objeto customer aninhado achatado em duas colunas e a lista tags unida 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 uma célula entre aspas só quando ela contém o delimitador, uma aspa ou uma quebra de linha, e duplicar qualquer aspa interna. Essa regra é toda a lógica de aspas do CSV, e acertá-la é a diferença entre um arquivo que abre limpo e um arquivo que desloca colunas em silêncio.

O script é deliberadamente curto para que você possa lê-lo antes de executá-lo. Ele pega a união de todas as colunas entre as linhas, então uma linha sem um campo recebe uma célula vazia, o que corresponde à página do conversor. Se você precisa de fluxo para arquivos enormes, ou de renomeação de colunas, essas são adições a este script, não substituições dele.

Método 5: ferramentas que você já tem, VS Code e Excel offline

Mais dois métodos 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 de VS Code com link abaixo. No Excel, o Power Query lê um arquivo JSON do seu disco e o transforma em uma tabela sem que o arquivo saia da sua máquina: Dados, Obter Dados, De Arquivo, De JSON, depois expanda as colunas e carregue. Ambos funcionam totalmente offline depois que a ferramenta está instalada.

Esses métodos trocam controle por conveniência. VS Code e Excel decidem o tratamento das colunas para você, e os padrões deles costumam ser bons para dados planos e às vezes surpreendentes para dados aninhados. Se a saída parecer errada, o diagnóstico é o mesmo de todos os outros lugares: verifique se os valores aninhados foram achatados ou deixados como texto JSON, e verifique o delimitador ao abrir. Para um arquivo que você converte uma vez, qualquer um dos métodos vence instalar algo novo. Para um arquivo que você converte toda semana, um script que é seu vence os dois.

Quando o local não basta, e o que fazer então

A conversão local tem três limites reais, e nomeá-los evita forçar um método local onde ele não se encaixa. O primeiro é colaboração: se cinco pessoas precisam da mesma conversão com as mesmas configurações, cinco scripts se distanciam e uma página compartilhada continua consistente. O segundo é acesso à máquina: em um computador emprestado ou bloqueado, você pode não conseguir instalar Python, jq ou Node, e então a página executada no cliente continua sendo o seu método local. O terceiro é escala: um arquivo maior do que a memória vai sobrecarregar todos os métodos aqui, e a correção é dividir o arquivo ou transmiti-lo linha por linha, não um conversor diferente.

Há também um limite que as pessoas esquecem: a conversão local não corrige dados ruins. Um script converte exatamente o que o arquivo contém, incluindo campos faltando, tipos misturados e formas inconsistentes. Se a mesma exportação às vezes tem um campo e às vezes não, todos os métodos deste guia dão a você a união de colunas com espaços em branco, o que é honesto mas pode não ser o que a sua planilha espera. Corrija a exportação de origem quando puder, e documente os espaços em branco quando não puder.

Higiene local de arquivos: quatro verificações antes de confiar no CSV

Uma conversão local só está pronta quando a saída confere, e as verificações levam menos de um minuto. Primeiro, guarde o JSON original. Nunca converta no lugar sobrescrevendo a origem, porque uma conversão perde informação: tipos viram texto, estrutura aninhada vira nomes de colunas, e não há caminho de volta para a árvore original só a partir do CSV. Segundo, nomeie a saída para que ela ordene bem: orders-2026-10-25.csv vence output-final-v2.csv, e a data diz de qual exportação ela veio.

Terceiro, conte as linhas. O CSV deveria 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 escolhendo a lista errada de uma resposta embrulhada. Quarto, abra o CSV com o delimitador certo. Um arquivo que abre como uma única coluna quase nunca é dado quebrado; é uma incompatibilidade de delimitador entre o arquivo e a planilha, e reimportar com o delimitador correspondente corrige isso. A página do conversor, o módulo csv do Python, o jq e o script Node acima colocam aspas conforme o delimitador ativo, então uma abertura em uma única coluna é um problema de abertura, não um problema de conversão.

Solução de problemas em conversões locais

Os mesmos quatro problemas aparecem em todos os métodos locais, e cada um tem uma correção. Arquivo não encontrado significa que o terminal está em uma pasta diferente da pasta do arquivo; confira o caminho antes de qualquer outra coisa. JSON inválido significa que o arquivo de origem está quebrado perto da posição informada, geralmente uma aspa faltando ou uma vírgula sobrando; valide o arquivo e corrija a origem, porque nenhum conversor deveria adivinhar uma entrada quebrada. Uma abertura em uma única coluna significa incompatibilidade de delimitador no lado da abertura; reimporte e escolha o delimitador com o qual o arquivo foi gravado.

Dados aninhados aparecendo como texto JSON ilegível nas células significam que o achatamento foi pulado: o script curto de Python e o comando de uma linha do jq não achatam, então use as variantes com achatamento acima ou a página do conversor com a opção de achatamento ligada. Colunas em uma ordem diferente da do arquivo significam que uma ferramenta ordenou as chaves; o jq precisa de keys_unsorted, e o script Node preserva a ordem da primeira aparição. Linhas faltando por completo significam que o localizador de linhas escolheu uma lista diferente da pretendida, o que acontece com respostas de API embrulhadas; aponte a ferramenta para a própria lista, ou desembrulhe a resposta primeiro.

Guias relacionados

Perguntas frequentes

O que converter JSON para CSV localmente significa?

Significa que a conversão roda na sua própria máquina em vez de em um servidor. Isso pode ser uma página de conversor executada no cliente rodando na sua aba do navegador, software instalado como VS Code ou Excel, ou um script que você mesmo executa em Python, jq ou Node. Nos três casos, o arquivo nunca precisa sair do seu computador.

O conversor desta página é local?

Sim. Cole ou envie JSON e a conversão roda dentro da sua aba do navegador, com o resultado devolvido como um arquivo baixado. Você pode verificar isso desconectando-se da rede e convertendo mesmo assim: ele continua funcionando. O único botão que usa a rede é o botão opcional de buscar a partir de URL, que carrega JSON de um endereço que você digita.

Preciso instalar algo para converter JSON para CSV localmente?

Não, se você usar a página do conversor, que não precisa de nada instalado. Se você quer um script repetível, o Python 3 já está instalado na maioria das máquinas de desenvolvedores e só a biblioteca padrão já basta. jq e Node são uma instalação cada e ambos rodam totalmente offline depois de instalados.

Qual método local é melhor para dados sensíveis?

Qualquer método em que você possa ver o código serve, mas um script curto que você mesmo lê é a opção mais forte, porque não há nada escondido em que confiar. Leia o script antes de executá-lo em dados sensíveis, guarde o JSON original e prefira uma página executada no cliente ou um script a qualquer ferramenta que envie o arquivo.

Posso converter JSON para CSV localmente sem internet?

Sim. A página do conversor funciona offline depois de carregada, e Python, jq, Node, VS Code e Excel rodam todos totalmente offline. O único passo que precisa de conexão é buscar JSON a partir de uma URL, o que é opcional e separado da conversão em si.

Por que o meu CSV local abre como uma única coluna?

Isso é uma incompatibilidade de delimitador no lado da abertura, não dados quebrados. A sua planilha dividiu o arquivo por um delimitador diferente daquele com o qual ele foi gravado. Reimporte o arquivo e escolha o delimitador correspondente, ou gere o CSV de novo com ponto e vírgula ou tab, e as colunas vão aparecer.

Converter localmente perde alguma informação?

Sim, a mesma informação que qualquer conversão perde. Valores são preservados mas tipos viram texto, objetos aninhados viram colunas com notação de ponto e listas viram células unidas ou texto JSON. Não há caminho de volta para a árvore original só a partir do CSV, então guarde sempre o arquivo JSON original.

Experimente o método local agora mesmo

Cole qualquer JSON no conversor desta página e veja a conversão acontecer dentro da sua aba do navegador, sem envio, sem cadastro, nada sai da sua máquina. Ou copie o script Python e execute-o nos seus próprios arquivos.

Abrir o conversor de JSON para CSV

Todos os guias