Como converter JSON em CSV no VS Code? 4 jeitos, do clique a um atalho (guia 2026)

Primeiro, o enquadramento honesto: o VS Code é um editor, não um conversor

Se você já procurou nos menus, não deixou passar nada. O VS Code não tem comando Converter para CSV, nenhum menu Exportar para JSON e nenhuma forma nativa de transformar um arquivo .json em um arquivo .csv. Isso não é um descuido: o VS Code é um editor de código, e a conversão de formato é o tipo de trabalho que ele delega a extensões, ao terminal e a tarefas. Quando você aceita isso, a pergunta deixa de ser “onde está o botão?” e passa a ser “qual dos quatro caminhos combina com este arquivo?”

Os quatro caminhos, em resumo: uma extensão para conversão com um clique dentro do editor; o terminal integrado para controle total com jq ou Python; uma tarefa tasks.json para conversões que você repete toda semana; e um conversor online para arquivos pontuais em que você quer zero configuração. Cada um é genuinamente o melhor em uma coisa, e cada um tem um modo de falha que os outros evitam. Este guia cobre os quatro, com os comandos exatos e as saídas exatas que eles produziram em um arquivo de teste aninhado real: um documento JSON com três pedidos, objetos de cliente aninhados, listas de itens e um total nulo.

Caminho 1: a extensão JSON2CSV (o mais rápido para um arquivo)

Para um único arquivo que você quer converter agora, uma extensão é o caminho de menor esforço. A indicada para instalar é a JSON2CSV, de khaeransori, no Visual Studio Code Marketplace. O README dela documenta o fluxo de forma clara: instale, abra um arquivo JSON, abra a Paleta de Comandos com Ctrl+Shift+P (Cmd+Shift+P no macOS), digite Convert JSON to CSV, e o CSV convertido abre em uma nova guia do editor, onde você o salva com Ctrl+S. Ela também converte no sentido contrário, de CSV para JSON, a partir da mesma paleta.

A instalação leva menos de um minuto: abra a exibição Extensões com Ctrl+Shift+X, pesquise json2csv e clique em Instalar na entrada publicada por khaeransori. Dois hábitos mantêm as instalações de extensões seguras em geral, e valem aqui tanto quanto em qualquer lugar: confira se o nome do editor confere antes de clicar em Instalar (existem extensões imitadoras com nomes parecidos para ferramentas populares) e dê uma olhada na contagem de downloads e na data da atualização mais recente. Uma extensão executa código na sua máquina com acesso aos seus arquivos, então um momento de verificação do editor vale mais do que qualquer lista de recursos.

Existem duas alternativas caso a JSON2CSV não sirva para você. A DataMorph (listada como Data Format Converter) converte entre CSV, JSON e Excel a partir do menu de contexto do botão direito ou da Paleta de Comandos, e anuncia conversão em lote de vários arquivos de uma vez, além de achatamento inteligente de JSON aninhado. A Algae Data é uma opção mais leve: abra um arquivo JSON, execute Algae: JSON to CSV na Paleta de Comandos, e o resultado abre em uma nova janela do editor. As três são extensões reais do Marketplace, com páginas públicas; escolha a que tem a lista de recursos que combina com os seus arquivos, não a que tem a descrição mais chamativa.

A limitação honesta do caminho da extensão: você está confiando seus dados a uma ferramenta de terceiros, e as escolhas de achatamento dela são dela. Se o seu JSON é profundamente aninhado ou se a ordem das colunas importa, os caminhos do terminal abaixo dão a você controle explícito sobre os dois, e é por isso que desenvolvedores que convertem JSON toda semana costumam acabar no caminho 2 ou 3.

Caminho 2: o terminal integrado, jq para dados planos, Python para dados aninhados

O terminal integrado é o superpoder do VS Code para este trabalho: aperte Ctrl+` (a tecla do acento grave) e você tem um shell completo dentro do editor, na pasta do seu projeto, com o seu arquivo aberto ao lado. Sem trocar de janela, sem uploads, e cada comando abaixo pode ser executado de novo. Duas ferramentas cobrem quase todos os arquivos: jq para conversões planas rápidas e Python para qualquer coisa aninhada.

Comece com o jq, o processador de JSON para linha de comando. Se o seu JSON é um array de objetos planos, sem objetos aninhados e sem arrays dentro das linhas, um comando faz a conversão inteira. Ele coleta todas as chaves de todas as linhas como cabeçalho e depois emite cada linha como CSV:

jq: JSON plano em CSV (verificado)

jq -r '(map(keys) | add | unique) as $cols | $cols, (.[] | [.[$cols[]]] | @csv)' flat.json > flat.csv

Em um arquivo de teste plano com dois pedidos (id, name, total), esse comando produziu exatamente isto: uma linha de cabeçalho id,name,total seguida por 1,"Ana",24.5 e 2,"Bo",9.0. Limpo, correto e instantâneo. Mas tente o mesmo comando com dados aninhados e o jq para você com honestidade: no nosso arquivo de teste aninhado com três pedidos, ele deu o erro “object is not valid in a csv row”, porque um objeto aninhado como customer não tem uma única célula de CSV onde morar. Esse erro é o jq dizendo a verdade: ferramentas planas precisam de linhas planas.

Caminho 2: o terminal integrado, jq para dados planos, Python para dados aninhados (continuação)

Para JSON aninhado, o jq ainda funciona se você nomear as colunas explicitamente. Esta receita puxa os campos que você quer por caminho, junta a lista items em uma célula com "; " e grava o CSV:

jq: JSON aninhado com colunas explícitas (verificado)

jq -r '["id","name","city","items","total"], (.[] | [.id, .customer.name, .customer.city, (.items | join("; ")), .total]) | @csv' orders.json > orders.csv

Executada contra o arquivo de teste aninhado, ela produziu um cabeçalho "id","name","city","items","total" e três linhas, incluindo 1,"Ana","Oslo","book; pen",24.5 e 3,"Cy","Trondheim","", para o pedido com lista de itens vazia e total nulo. Vale conhecer dois comportamentos do jq: o @csv coloca aspas em toda string (correto, embora barulhento), e null vira um campo vazio apenas quando cai em um contexto de string: a célula vazia de itens da terceira linha veio do join em uma lista vazia, enquanto o total nulo foi impresso como um campo vazio no fim da linha. Colunas explícitas significam controle explícito: você decide a ordem das colunas, os caminhos de aninhamento e o que cada lista vira.

Caminho 2: o terminal integrado, jq para dados planos, Python para dados aninhados (continuação)

Quando nomear cada coluna à mão fica cansativo, o Python é a ferramenta melhor. Salve este pequeno script como convert.py no seu projeto: ele achata objetos aninhados em colunas com notação de ponto (customer.name), junta listas simples com "; ", transforma null em célula vazia e grava um CSV correto, com o módulo csv padrão cuidando das aspas para você:

convert.py: script de conversão JSON para CSV com achatamento (verificado)

import json, csv, sys

def flatten(obj, prefix=""):
    out = {}
    if isinstance(obj, dict):
        for k, v in obj.items():
            key = f"{prefix}.{k}" if prefix else k
            out.update(flatten(v, key))
    elif isinstance(obj, list):
        out[prefix] = "; ".join(str(x) for x in obj if not isinstance(x, (dict, list))) if obj else ""
        for i, v in enumerate(obj):
            if isinstance(v, (dict, list)):
                out.update(flatten(v, f"{prefix}[{i}]"))
    else:
        out[prefix] = "" if obj is None else obj
    return out

rows = json.load(open(sys.argv[1]))
if isinstance(rows, dict):
    rows = [rows]
flat = [flatten(r) for r in rows]
cols = sorted({k for r in flat for k in r})
with open(sys.argv[2], "w", newline="", encoding="utf-8") as f:
    w = csv.DictWriter(f, fieldnames=cols)
    w.writeheader()
    w.writerows(flat)
print(f"wrote {sys.argv[2]}: {len(flat)} rows, {len(cols)} columns")

Execute-o no terminal integrado com python3 convert.py orders.json orders.csv. No mesmo arquivo de teste aninhado, ele imprimiu “wrote orders.csv: 3 rows, 5 columns” e produziu customer.city,customer.name,id,items,total como cabeçalho, com as linhas Oslo,Ana,1,book; pen,24.5 / Bergen,Bo,2,mug,9.0 / Trondheim,Cy,3,, , com o total nulo e a lista de itens vazia caindo como células vazias, exatamente como as regras de achatamento prometem. O script lida com as duas formas que as pessoas realmente encontram: um array de nível superior (o caso normal) e um único objeto de nível superior (embrulhado em uma tabela de uma linha). Tanto as duas receitas de jq quanto este script foram executados na máquina de build antes da publicação, e as saídas acima são as saídas reais deles, não ilustrações.

Caminho 3: salve como uma tarefa, um atalho, toda vez

Se você converte arquivos JSON mais de uma vez por mês, pare de redigitar comandos e salve a conversão como uma tarefa do VS Code. Uma tarefa é um comando nomeado em .vscode/tasks.json, executável em Terminal → Executar Tarefa ou com o atalho de teclado Ctrl+Shift+B. Ela transforma o caminho do Python acima em uma operação de um atalho sobre qualquer arquivo que você tenha aberto.

Crie .vscode/tasks.json no seu projeto com este conteúdo (o arquivo foi verificado como JSON válido antes da publicação):

.vscode/tasks.json: converter o arquivo aberto (parse verificado)

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "JSON to CSV: convert current file",
      "type": "shell",
      "command": "python3 ${workspaceFolder}/convert.py ${file} ${fileDirname}/${fileBasenameNoExtension}.csv",
      "problemMatcher": []
    }
  ]
}

Como funciona: ${file} é o arquivo aberto no seu editor ativo, ${fileDirname} é a pasta dele e ${fileBasenameNoExtension} é o nome dele sem .json. Ou seja, com orders.json aberto, a tarefa executa python3 convert.py nele e grava orders.csv ao lado dele. Abra qualquer arquivo JSON, aperte Ctrl+Shift+B, escolha a tarefa e o CSV aparece ao lado do arquivo de origem. O mesmo padrão funciona para as receitas de jq: substitua o comando pela linha de jq e use ${file} como entrada. Um cuidado: tarefas executam comandos de shell com as permissões do seu usuário, então só adicione tarefas de fontes em que você confia, a mesma regra das extensões, aplicada à configuração.

O caminho da tarefa é também onde o script Python compensa em relação ao jq: um script mais uma tarefa lida com arquivos planos, arquivos aninhados, objetos avulsos e arrays, sem edição de comando por arquivo. Se você converte exportações da mesma API toda semana, este é o caminho que vale a pena.

Caminho 4: quando pular o VS Code por completo e usar um conversor online

Há três situações em que sair do editor é a decisão certa. Primeira, um arquivo pontual em uma máquina onde você não pode instalar extensões ou não tem jq ou Python à mão: um notebook emprestado, uma máquina de trabalho bloqueada, um Chromebook. Segunda, um JSON cujo aninhamento é incômodo o bastante para que escrever caminhos jq explícitos pareça trabalho: um conversor online com botão de achatamento transforma a árvore inteira em colunas com um clique, e você vê a prévia antes de baixar. Terceira, compartilhamento: se o CSV é para um colega que não usa o VS Code, converter no navegador e enviar o arquivo pronto é mais simples do que explicar a sua cadeia de ferramentas.

O caminho online neste site roda inteiramente no seu navegador: cole o JSON ou envie o arquivo, a conversão acontece no lado do cliente sem upload para um servidor, os dados aninhados achatam para colunas com notação de ponto e o download é em UTF-8 puro. Para um usuário do VS Code, a comparação honesta é: o conversor online troca a repetibilidade de uma tarefa por zero configuração e uma prévia instantânea. Use os caminhos do editor quando a conversão se repete; use o caminho do navegador quando ela não se repete.

Inspecionando o resultado dentro do VS Code (e por que o texto bruto é a verdade)

Qualquer que seja o caminho, inspecione o CSV no VS Code antes de confiar nele. O VS Code mostra o arquivo bruto, as vírgulas, aspas e quebras de linha reais, enquanto uma planilha mostra a interpretação dela sobre eles. Se os dois discordarem, o texto bruto é a verdade e a planilha está adivinhando. Duas extensões facilitam a inspeção: a Edit CSV abre um CSV como uma tabela editável no estilo planilha dentro do editor, e a Rainbow CSV colore cada coluna com uma cor diferente para que linhas desalinhadas saltem aos olhos.

O relato mais comum de “meu CSV está quebrado” é um arquivo que abre no Excel como uma única coluna longa. Nove vezes em dez o arquivo está bom: o Excel adivinhou o delimitador errado (muitas vezes um arquivo de ponto e vírgula aberto como vírgula) ou a codificação errada. Abra o arquivo no VS Code primeiro: se as vírgulas e as aspas parecem certas no texto bruto, o arquivo está certo, e a correção é do lado da importação (Excel: Dados → De Texto/CSV, escolha o delimitador e UTF-8 65001). A barra de status na parte de baixo do VS Code também mostra a codificação do arquivo; se um arquivo parece embaralhado, use Arquivo → Salvar com Codificação → UTF-8 para normalizá-lo, e Salvar com Codificação → UTF-8 com BOM somente se uma ferramenta específica do Windows exigir um BOM.

Solução de problemas: os quatro erros que usuários do VS Code realmente encontram

JSON inválido, sinalizado antes de converter. Se o arquivo tem rabiscos vermelhos ou o painel Problemas lista erros, corrija isso primeiro: nenhum conversor aceita JSON malformado. Duas armadilhas específicas do VS Code: arquivos no estilo de configurações permitem comentários e vírgulas finais (isso é JSONC, não JSON), e uma vírgula final solta depois do último elemento é o erro de sintaxe mais comum. Remova comentários e vírgulas finais antes de converter; o próprio serviço de linguagem JSON do VS Code costuma apontar a linha exata.

Um único objeto em vez de um array. APIs costumam devolver {"data": [...], "total": 2} ou um {...} avulso em vez de um array puro. O script Python acima lida com um objeto avulso embrulhando-o em uma linha, e para um objeto wrapper você quer as linhas dentro dele: extraia o array primeiro (em jq, .data | ...; em Python, rows = json.load(...)["data"]), ou o conversor vai dar a você uma linha com o array inteiro transformado em texto dentro de uma célula.

Dados aninhados que “somem”. O achatamento sempre faz escolhas: listas de objetos não têm representação de célula única, e o script Python acima junta apenas listas de valores simples, recorrendo a listas de objetos com chaves indexadas (items[0].name). Se as suas listas contêm objetos e a saída parece errada, isso é a regra de achatamento aparecendo, não perda de dados: decida por coluna se você quer a lista unida, expandida em linhas ou descartada, e diga isso no script em vez de aceitar um padrão em silêncio.

Arquivos enormes. Uma extensão convertendo um arquivo JSON de 200 MB dentro do editor pode travar a interface; os caminhos do terminal transmitem melhor, e o jq em particular lida com arquivos grandes sem carregar uma prévia. Se o VS Code parecer lento, esse é o sinal para usar o terminal: jq ou Python na linha de comando, com o editor apenas mostrando o resultado.

Qual caminho você deve escolher?

Um arquivo, agora, sem configuração: a extensão JSON2CSV. Instale, Paleta de Comandos, salve a nova guia. Arquivos que você converte toda semana: o script Python mais uma tarefa tasks.json. Um atalho, mesmo resultado toda vez. Um arquivo plano rápido e você gosta do terminal: o one-liner do jq. Um arquivo pontual em uma máquina bloqueada, ou um aninhamento incômodo que você quer pré-visualizar antes de confirmar: o conversor online. Nenhum deles é “o” jeito do VS Code, porque o VS Code deliberadamente não tem um único jeito nativo: o editor dá a você as peças, e a combinação certa é a que combina com a frequência com que você converte e com o quão aninhados são os seus dados.

Abrir o conversor gratuito de JSON para CSV

Guias relacionados

Perguntas frequentes

Como converter JSON em CSV no VS Code?

O VS Code não tem conversor nativo, então adicione um dos quatro caminhos: instale a extensão JSON2CSV e execute Convert JSON to CSV na Paleta de Comandos; use o terminal integrado com jq (dados planos) ou um script Python (dados aninhados); salve a conversão como uma tarefa tasks.json para repetições de um atalho; ou cole o JSON em um conversor online gratuito para um arquivo pontual com zero configuração.

Qual é a melhor extensão do VS Code para JSON para CSV?

A JSON2CSV, de khaeransori, é a mais direta: instale-a na exibição Extensões, abra o seu arquivo JSON, execute Convert JSON to CSV na Paleta de Comandos, e o CSV abre em uma nova guia. A DataMorph (Data Format Converter) adiciona conversão para Excel e processamento em lote; a Algae Data é uma alternativa mais leve. Sempre confira o nome do editor antes de instalar qualquer extensão.

Dá para converter JSON em CSV no VS Code sem extensão?

Sim. Use o terminal integrado (Ctrl+`). Para arrays JSON planos: jq -r '(map(keys) | add | unique) as $cols | $cols, (.[] | [.[$cols[]]] | @csv)' arquivo.json > arquivo.csv. Para JSON aninhado, use o jq com caminhos de coluna explícitos ou um pequeno script Python que achata objetos aninhados em colunas com notação de ponto. Os dois caminhos foram testados com dados reais para este guia.

Por que o jq falha com “object is not valid in a csv row”?

Porque uma linha contém um objeto ou array aninhado, e linhas de CSV só comportam valores planos. A receita genérica de @csv do jq só funciona em linhas planas. Corrija nomeando as colunas explicitamente (jq -r '["id","name",...], (.[] | [.id, .customer.name, ...]) | @csv') ou achatando primeiro com um script Python que transforma objetos aninhados em colunas com notação de ponto.

Como automatizar a conversão de JSON para CSV no VS Code?

Salve uma tarefa em .vscode/tasks.json que executa o seu comando de conversão no arquivo aberto, por exemplo python3 ${workspaceFolder}/convert.py ${file} ${fileDirname}/${fileBasenameNoExtension}.csv, e depois aperte Ctrl+Shift+B (Terminal → Executar Tarefa) com qualquer arquivo JSON aberto. O CSV é gravado ao lado do arquivo de origem toda vez, sem redigitar.

Por que o meu CSV do VS Code abre como uma coluna no Excel?

Em geral o arquivo está bom e o Excel adivinhou o delimitador ou a codificação errados. Confira o texto bruto no VS Code primeiro: se as vírgulas e as aspas parecem certas lá, o arquivo está certo. Reimporte no Excel via Dados → De Texto/CSV, escolha o delimitador correto e a codificação 65001 (UTF-8), em vez de clicar duas vezes no arquivo.

O VS Code converte JSONC ou JSON com comentários para CSV?

Não diretamente. Comentários e vírgulas finais são JSONC, não JSON, e nenhum conversor os aceita. Remova comentários e vírgulas finais primeiro (o painel Problemas do VS Code sinaliza as linhas exatas) e depois converta o JSON limpo. O mesmo vale para arquivos de configurações e arquivos .code-workspace, que são JSONC por design.

Arquivo pontual? Converta no navegador, sem extensão

Cole o JSON ou envie um arquivo: os dados aninhados achatam em colunas limpas, delimitadores e aspas são automáticos e o download é em UTF-8 puro. Grátis, sem cadastro, roda inteiramente no seu navegador.

Abrir o conversor de JSON para CSV

Todos os guias