O que é um arquivo INI?

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

A extensão é .ini e o nome por extenso é INI Configuration. Os dois importam menos do que aquilo que o arquivo consegue carregar, e é disso que trata o resto desta página.

Ele remonta a 1985.

A um formato que se manteve legível por tanto tempo dá para confiar algo que você quer de volta daqui a dez anos.

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.

Ele ainda abre em todo lugar e programas antigos ainda o escrevem, mas nada de novo está sendo construído em volta. Converta o que quiser guardar e não o escolha para algo que começa hoje.

INI 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.

Notepad e Visual Studio Code leem 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.

INI 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.

O INI veio dos primeiros Windows, onde guardava as configurações do sistema e de cada aplicativo. Nunca foi padronizado — nenhum documento define ele, nenhum comitê é dono dele, e todo programa que lê um implementa seu próprio dialeto.

O núcleo é universal: cabeçalhos de seção entre colchetes, e linhas de chave igual valor abaixo deles. Tudo além desse núcleo é cara ou coroa. Se um ponto e vírgula ou uma cerquilha inicia um comentário. Se um valor pode estar entre aspas, e o que acontece com as aspas. Se as chaves diferenciam maiúsculas de minúsculas. Se um valor pode continuar numa segunda linha. Se seções podem se aninhar, o que na maioria dos dialetos não podem. Dois programas lendo o mesmo arquivo podem legitimamente discordar, e os dois estão certos.

Escreva timeout=30, e o arquivo contém os caracteres 3 e 0. Se isso vira um número, e se significa segundos ou milissegundos, é decidido inteiramente pelo programa que lê. O mesmo vale para true, yes, on e 1 — todos jeitos comuns de escrever um booleano, nenhum definido pelo formato, e cada biblioteca aceitando um subconjunto diferente.

Essa é a diferença prática em relação ao JSON, YAML ou TOML, todos com tipos. É por isso que arquivos de configuração INI normalmente vêm acompanhados de documentação ou comentários explicando o que os valores significam, e por que mover um arquivo de configuração entre duas implementações do mesmo programa é mais perigoso do que parece.

No Windows, ainda, em alguns lugares: desktop.ini controlando como uma pasta é exibida, configuração de boot e driver, e uma longa cauda de aplicativos que nunca tiveram motivo para mudar. Jogos são uma fonte particularmente rica — um número enorme de jogos de PC guarda os ajustes de gráficos e controle num INI, o que explica os guias de ajuste estarem cheios de instruções para editar um.

Em outros lugares, sobrevive em ferramentas anteriores às alternativas modernas: o php.ini do PHP, a configuração do Git, o setup.cfg e ferramentas de empacotamento do Python, arquivos de unidade do systemd, e vários utilitários pequenos. Projetos novos tendem a escolher TOML ou YAML, mas nada nas instalações existentes vai ser reescrito.

Qualquer editor de texto. Duas regras cobrem a maior parte do dano que as pessoas causam: copie o arquivo antes de mudar, e mude uma coisa por vez — um programa que não inicia por causa de um arquivo de configuração ruim raramente te diz qual linha ele não gostou.

Depois os detalhes que realmente causam falhas. Salve como UTF-8 sem marca de ordem de byte, porque os bytes invisíveis no início do arquivo quebram o primeiro cabeçalho de seção em muitos leitores. Não adicione espaços ao redor do sinal de igual a menos que você saiba que o leitor remove eles, já que alguns não removem, e seu valor vira um espaço no início mais o texto. E deixe a citação em paz: se os valores existentes não têm aspas, adicionar aspas pode acrescentar dois caracteres ao valor em vez de delimitar ele.

Em ser óbvio. Uma pessoa que nunca viu o arquivo consegue abrir, achar o ajuste chamado fullscreen, mudar false para true, e estar certa. Essa é uma propriedade real, e é por isso que o formato sobreviveu a tudo que foi desenhado para substituir ele nos anos 1990.

Também falha de forma graciosa no caso raso: uma chave desconhecida normalmente é ignorada em vez de fatal, então um arquivo de configuração escrito para uma versão mais nova de um programa geralmente continua funcionando com uma mais antiga. As alternativas são mais rígidas, o que é melhor para correção e pior para a pessoa editando as configurações de um jogo à meia-noite.

Quando a configuração cresceu além de seções planas de texto. Estrutura aninhada, listas, datas, números que precisam ser números, ou qualquer valor em que a diferença entre a string "false" e o booleano false importa — tudo isso é onde o INI para de ajudar e começa a esconder bugs.

O TOML foi desenhado como a resposta exatamente para isso: parece com INI, então ninguém precisa aprender uma forma nova, e tem uma especificação, tipos reais e aninhamento definido. O YAML é o outro destino comum e é mais poderoso e consideravelmente mais fácil de errar. Se um arquivo está prestes a crescer, o TOML é o passo menor e o que mantém a legibilidade que fazia o INI valer a pena usar.