Cómo Crear un Archivo INI: Reglas de Sintaxis, Secciones y Parsers

Un archivo INI es un archivo de configuración de texto plano que almacena ajustes como pares clave-valor, opcionalmente agrupados en secciones con nombre. El nombre viene de «initialisation» (inicialización) — los archivos INI se usaban para inicializar aplicaciones de Windows con sus ajustes antes de que existiera el Registro de Windows. El formato nunca tuvo una especificación formal, pero surgió un estándar de facto por su uso generalizado.

Dónde se usan hoy los archivos INI

• Empaquetado Python — `setup.cfg`, `tox.ini`, `pytest.ini`, `mypy.ini`, `.flake8`
• Tiempo de ejecución PHP — `php.ini` controla globalmente los ajustes del intérprete PHP
• MySQL / MariaDB — `my.ini` (Windows) y `my.cnf` (Unix) configuran el servidor de base de datos
• Git — `.gitconfig` y `.git/config` usan un formato tipo INI para ajustes de repositorio y usuario
• Wine — `wine.inf` configura la capa de compatibilidad de Windows en Linux y macOS
• Aplicaciones Windows — miles de aplicaciones de escritorio antiguas y modernas guardan preferencias en archivos `.ini` en la carpeta AppData

INI frente al Registro de Windows

Microsoft trasladó los ajustes de las aplicaciones Windows al Registro a principios de los años 90 por razones de rendimiento y gestión centralizada. Sin embargo, muchos desarrolladores siguen prefiriendo los archivos INI por su portabilidad — un archivo INI puede inspeccionarse y editarse con cualquier editor de texto, comprometerse a un control de versiones y copiarse entre máquinas sin herramientas de exportación/importación. El Registro no puede.

A pesar de la falta de una especificación formal, la sintaxis INI sigue convenciones consistentes en prácticamente todos los parsers. Estas son las reglas en las que puedes confiar sin importar qué lea tu archivo.

Un archivo INI es el formato de configuración más simple posible: secciones entre corchetes, pares clave-valor debajo y punto y coma para comentarios. Todo lo demás es específico del parser.

Reglas universales

• Un par clave-valor por línea — `key = value` o `key=value`; el espacio alrededor de `=` es opcional pero el espaciado consistente es legible
• Encabezados de sección — `[NombreSección]` en su propia línea; sin contenido tras el corchete de cierre
• Líneas de comentario — empiezan con `;` para máxima compatibilidad; `#` lo soportan algunos parsers (`configparser` de Python, herramientas Linux) pero no las APIs nativas de Windows
• Líneas en blanco — ignoradas por todos los parsers; úsalas libremente para separar grupos lógicos dentro de una sección
• Sin anidamiento — INI es plano: las secciones contienen pares clave-valor, no otras secciones
• Valores de cadena — todos los valores son cadenas salvo que el parser los convierta; `count = 5` es la cadena "5" para la mayoría de los parsers

Lo que ve el parser

El parser construye un mapa de dos niveles: nombre de sección → clave → valor. Si un archivo no tiene encabezados de sección, los valores están en una sección implícita «por defecto» — el `configparser` de Python la llama `DEFAULT`. Que el parser fusione la sección por defecto con las secciones con nombre varía. Las claves y nombres de sección se tratan casi universalmente como insensibles a mayúsculas por convención, aunque no está garantizado por todas las implementaciones.

Crear un archivo INI toma menos de cinco pasos. La única herramienta necesaria es un editor de texto plano — cualquier editor que guarde como UTF-8 o ASCII sin marca de orden de bytes (BOM) funciona correctamente.

Los tres elementos estructurales de un archivo INI — secciones, claves y valores — tienen reglas y casos límite que vale la pena entender antes de escribir una configuración que será leída por el parser de otra persona.

Convenciones de nombres de sección

Los nombres de sección van entre corchetes y aparecen en su propia línea. Pueden contener letras, números, espacios y la mayoría de la puntuación — pero los espacios en nombres de sección están pobremente soportados por algunos parsers y deben evitarse. Usa `[DatabaseConfig]` o `[database_config]` en lugar de `[database config]`. Los nombres de sección duplicados se fusionan o causan un error según el parser — trátalos como prohibidos y valida con el Validador INI para detectar duplicados.

Reglas de nombres de claves

Las claves no deben contener el signo `=` ni un salto de línea. Más allá de eso, las convenciones varían, pero la práctica más segura es usar solo letras minúsculas, dígitos y guiones bajos — las mismas reglas que los nombres de variables de Python. Evita los guiones en las claves si planeas leerlas en Python con `configparser`, ya que Python devuelve las claves tal cual y las claves con guiones no pueden accederse como atributos.

Tipos de valor y valores multilínea

Todos los valores en archivos INI son cadenas salvo que tu parser los convierta explícitamente. `enabled = true` es la cadena "true" — tu código debe convertirla a un booleano. El `configparser` de Python proporciona los métodos `getboolean()`, `getint()` y `getfloat()` para este propósito. Los valores multilínea están soportados por algunos parsers (el `configparser` de Python trata las líneas con espacios iniciales como continuaciones del valor anterior) pero no todos — consulta la documentación de tu parser antes de confiar en esto.

La sección DEFAULT

El `configparser` de Python trata una sección llamada `[DEFAULT]` (insensible a mayúsculas) como una sección especial de respaldo. Cualquier clave definida en `[DEFAULT]` está disponible en todas las demás secciones como respaldo — si una sección no define una clave, se devuelve el valor de `[DEFAULT]`. Es un comportamiento específico de Python que no se encuentra en la mayoría de otros parsers. Si escribes archivos INI específicamente para Python, `[DEFAULT]` es una forma útil de definir valores compartidos sin repetirlos en cada sección.

Los comentarios y la codificación de caracteres son los dos aspectos de los archivos INI con más probabilidad de causar problemas silenciosos cuando los archivos se comparten entre distintas herramientas, sistemas operativos o lenguajes de programación.

Caracteres de comentario: ; frente a #

El punto y coma (`;`) es el carácter de comentario universalmente soportado — funciona en el `configparser` de Python, las APIs nativas de Windows, `parse_ini_file()` de PHP, MySQL y prácticamente cualquier otro parser INI. La almohadilla (`#`) está soportada por el `configparser` de Python y la mayoría de parsers basados en Linux, pero no por `GetPrivateProfileString()` de Windows. Si tu archivo INI solo lo leerá Python, cualquier carácter es seguro. Para archivos multiplataforma, usa exclusivamente `;`.

Codificación de caracteres: UTF-8 frente a Windows-1252

Guarda los archivos INI como UTF-8 sin BOM para herramientas modernas. El BOM (marca de orden de bytes, el carácter invisible `\uFEFF` al inicio de algunos archivos UTF-8 guardados por herramientas de Windows) causa problemas con parsers que lo tratan como parte del primer nombre de clave. El `configparser` de Python maneja UTF-8 de forma nativa desde Python 3. Si escribes un archivo INI para una aplicación Windows heredada que espera codificación Windows-1252, ajusta lo que la aplicación espera — mezclar codificaciones es una fuente común de corrupción de caracteres en los valores.

Finales de línea

Los archivos INI funcionan tanto con finales de línea de Windows (CRLF, `\r\n`) como de Unix (LF, `\n`). Usa la convención de finales de línea de tu plataforma destino. Si editas un archivo INI en Windows para despliegue en Linux, configura tu editor de texto para guardar con finales de línea LF y evitar que el carácter de retorno de carro aparezca en los valores en parsers Linux. El Formateador INI normaliza finales de línea y espaciado en una sola pasada.

La mayoría de los lenguajes proporcionan un parser integrado o de biblioteca estándar para archivos INI. Aquí están los enfoques estándar para los entornos más comunes.

Python: configparser

El módulo `configparser` de Python es la forma estándar de leer archivos INI en Python. Impórtalo, crea una instancia `ConfigParser()`, llama a `.read()` con tu nombre de archivo y accede a los valores con `config["NombreSección"]["clave"]` o `config.get("NombreSección", "clave")`. El método `.get()` acepta un argumento `fallback` que devuelve un valor por defecto cuando falta la clave — útil para valores de configuración opcionales. Usa `getboolean()`, `getint()` y `getfloat()` para valores tipados en lugar de convertir cadenas manualmente.

PHP: parse_ini_file()

PHP proporciona `parse_ini_file($filename, $process_sections)` como función integrada. Con `$process_sections = true`, la función devuelve un array asociativo anidado organizado por nombre de sección. Con `false`, devuelve un array plano con todas las claves fusionadas. El parser de PHP es estricto con ciertos caracteres especiales en valores sin comillas — valores que contengan =, llaves de apertura/cierre, |, &, ~, !, [, ] deben ir entre comillas en el archivo INI para parsearse correctamente.

Node.js y otros entornos

Node.js no tiene un parser INI integrado, pero el paquete npm `ini` (licencia MIT) proporciona una interfaz estándar `parse()` y `stringify()`. Para Java, la librería `org.ini4j` es la elección estándar. Para Go, el paquete `gopkg.in/ini.v1` es la opción más usada. En cada caso, la librería maneja la misma estructura de dos niveles sección/clave — las formas de la API varían pero el formato subyacente es idéntico.

INI no siempre es el formato de configuración correcto. Entender dónde encaja — y dónde TOML o YAML es una mejor elección — te ayuda a tomar la decisión correcta para nuevos proyectos.

Cuándo usar INI

INI es la elección correcta cuando tu configuración tiene dos niveles de profundidad (secciones y pares clave-valor planos), cuando el parser destino ya espera formato INI (PHP, ecosistema Python, MySQL, Git) y cuando quieres el formato más simple posible que cualquier desarrollador pueda leer sin conocimiento previo. No es apropiado para configuraciones que necesiten arrays, objetos anidados o datos tipados.

Cuándo usar TOML o YAML en su lugar

Elige TOML cuando tu configuración necesite valores tipados, arrays o tablas en línea y quieras una especificación estricta con parsing predecible. TOML es el formato de `pyproject.toml`, `Cargo.toml` y los archivos de configuración de Hugo. Elige YAML cuando necesites estructuras profundamente anidadas o trabajes en un ecosistema donde YAML ya es estándar — Kubernetes, GitHub Actions, Docker Compose y Ansible son entornos YAML-first.