O que é um arquivo TOML?

TOML é um formato de texto puro que abre em qualquer editor. Ele é usado para a edição.

A extensão é .toml e o nome por extenso é Tom's Obvious Minimal Language. Os dois importam menos do que aquilo que o arquivo consegue carregar, e é disso que trata o resto desta página.

Ele remonta a 2013. A especificação é TOML 1.0.

A idade interessa por um motivo prático: quanto mais antigo o formato, mais programas tiveram tempo de aprendê-lo.

Ela está publicada por inteiro, então dá para implementá-la a partir do documento em vez de por observação — é por isso que o formato aparece em tantos programas e por isso que arquivos escritos há vinte anos ainda abrem. Especificação publicada não é o mesmo que livre de royalties: quando o formato embrulha um codec, o licenciamento das patentes é uma questão à parte, que a norma não resolve.

TOML guarda o conteúdo exatamente. Salvar de novo não muda nada, então dá para abrir, editar e salvar quantas vezes você quiser sem acumular estrago — e é isso que faz dele um formato de trabalho e não de entrega.

TOML tem sintaxe de comentário — essa é a diferença entre um arquivo que uma pessoa mantém e um que um programa escreve. Os comentários são a primeira coisa perdida na conversão para um formato que não os tem, e nada avisa.

Visual Studio Code lê esse formato, e a maioria dos programas do mesmo tipo também.

Quando um arquivo não abre, o formato raramente é o problema — mais comum é o programa ser mais antigo que ele. Converter para algo mais antigo é o caminho confiável, e é para isso que serve o resto deste site.

Nenhum navegador lê o formato.

Esse é de longe o motivo mais comum para convertê-lo: não que o formato seja ruim, mas que o lugar onde você quer mostrar o arquivo não consegue lê-lo.

TOML foi feito para ser aberto e alterado. Mantenha o arquivo nesse formato enquanto o trabalho estiver em andamento e exporte a partir dele sempre que precisar de uma cópia pronta.

TOML parece INI e se comporta como formato de dados. Um valor escrito como 30 é inteiro, 30.0 é float, true é booleano, "30" é string, e 2026-08-05 é data — o formato define todos eles, então todo leitor concorda e nenhum programa precisa adivinhar o que o autor quis dizer.

Essa única propriedade é a maior parte do motivo dele existir. Bugs de configuração se concentram exatamente nessa ambiguidade: uma flag lida como a string "false" e considerada verdadeira, um número de versão silenciosamente virando float, um número de porta chegando como texto. Um formato com tipos remove essa classe inteira.

YAML é mais capaz e bem mais fácil de errar, e TOML foi escrito em resposta direta a isso. Estrutura em YAML é expressa por indentação, então um espaço fora do lugar muda o significado de um documento sem produzir erro, e o arquivo continua interpretando — em algo diferente do pretendido.

Depois há a inferência de tipo. YAML mais antigo lê "no" como booleano, então um código de país ou uma coluna de resposta vira false. Números de versão como 1.20 viram o float 1.2. Cada um desses já causou queda real de sistema. TOML não tem nenhum: a estrutura é explícita, e um valor é o que sua sintaxe diz que é.

Rust colocou em toda parte primeiro — todo projeto Cargo tem um Cargo.toml — e Python seguiu de forma decisiva: pyproject.toml é hoje o lugar padrão para configuração de build, e a linguagem embarca um leitor TOML na biblioteca padrão.

Além desses, Hugo e vários geradores de site estático, Netlify, Poetry, Ruff, e uma sequência constante de ferramentas mais novas que queriam configuração editável por humano sem o risco da indentação.

Um cabeçalho entre colchetes é uma tabela, palavra do TOML para seção. Aninhamento é feito com ponto: [tool.ruff.lint] declara uma tabela dentro de outra dentro de outra, e os pontos são estrutura, não parte de um nome — exatamente onde o INI para e o TOML continua.

Colchete duplo é a parte que pega todo mundo. [[bin]] repetido três vezes não redefine uma tabela três vezes; declara um array de tabelas, três entradas numa lista. É como se expressa "várias coisas do mesmo tipo" — três binários, quatro dependências, uma lista de autores.

TOML entende data e hora diretamente: uma data sozinha, uma hora sozinha, e um timestamp com ou sem fuso. São valores do mesmo jeito que inteiros são, não strings que algo precisa interpretar depois.

É um recurso pequeno que remove um incômodo persistente. Configuração contendo data de lançamento, expiração ou cronograma não precisa mais de um formato de string combinado, documentado num comentário e reimplementado em cada consumidor.

Dado profundamente aninhado. TOML é desenhado para ser plano e legível, e uma vez que a estrutura desce três ou quatro níveis, os nomes de cabeçalho ficam longos e o arquivo fica mais difícil de acompanhar que o JSON que ele está tentando substituir.

Dado gerado por máquina é o outro caso. TOML é para arquivos que pessoas editam; JSON é para arquivos que programas trocam, e é menor, mais rápido de interpretar e suportado em toda parte. Usar TOML como formato de intercâmbio de dados é possível e não ganha nada.

Qualquer editor de texto, e um com suporte a TOML vale a pena para qualquer coisa substancial — vai mostrar uma string não terminada ou um cabeçalho de tabela malformado imediatamente, onde um leitor vai reportar isso como falha numa linha bem distante.

Dois hábitos evitam a maioria dos erros. Mantenha toda chave dentro do cabeçalho de tabela a que ela pertence, já que uma chave escrita acima do primeiro cabeçalho vai parar no nível de topo e silenciosamente não faz nada. E não coloque número ou booleano entre aspas.