Comment créer un fichier INI : règles de syntaxe, sections et parseurs

Un fichier INI est un fichier de configuration en texte brut qui stocke les paramètres sous forme de paires clé-valeur, éventuellement regroupées en sections nommées. Le nom vient de « initialisation » — les fichiers INI servaient à initialiser les applications Windows avec leurs paramètres avant l'existence du Registre Windows. Le format n'a jamais eu de spécification formelle, mais un standard de fait s'est dégagé d'un usage répandu.

Où les fichiers INI sont utilisés aujourd'hui

• Empaquetage Python — `setup.cfg`, `tox.ini`, `pytest.ini`, `mypy.ini`, `.flake8`
• Exécution PHP — `php.ini` contrôle globalement les paramètres de l’interpréteur PHP
• MySQL / MariaDB — `my.ini` (Windows) et `my.cnf` (Unix) configurent le serveur de base de données
• Git — `.gitconfig` et `.git/config` utilisent un format proche d’INI pour les dépôts et les réglages utilisateur
• Wine — `wine.inf` configure la couche de compatibilité Windows sur Linux et macOS
• Applications Windows — des milliers d’applications de bureau anciennes et modernes stockent leurs préférences dans des fichiers `.ini` du dossier AppData

INI vs le Registre Windows

Microsoft a migré les paramètres des applications Windows vers le Registre au début des années 1990 pour des raisons de performance et de gestion centralisée. Cependant, beaucoup de développeurs continuent de préférer les fichiers INI pour leur portabilité — un fichier INI peut être inspecté et modifié avec n'importe quel éditeur de texte, versionné et copié entre machines sans outil d'export/import. Le Registre ne le peut pas.

Malgré l'absence de spécification formelle, la syntaxe INI suit des conventions cohérentes dans pratiquement tous les parseurs. Voici les règles sur lesquelles vous pouvez compter, quel que soit ce qui lit votre fichier.

Un fichier INI est le format de configuration le plus simple possible : des sections entre crochets, des paires clé-valeur en dessous et des points-virgules pour les commentaires. Tout le reste est spécifique au parseur.

Règles universelles

• Une paire clé-valeur par ligne — `key = value` ou `key=value` ; l’espace autour de `=` est facultatif mais un espacement cohérent reste lisible
• En-têtes de section — `[NomSection]` seul sur sa ligne ; aucun contenu après le crochet fermant
• Lignes de commentaire — commencent par `;` pour une compatibilité maximale ; `#` est pris en charge par certains parseurs (`configparser` Python, outils Linux) mais pas par les API natives Windows
• Lignes vides — ignorées par tous les parseurs ; utilisez-les librement pour séparer les groupes logiques au sein d’une section
• Pas d’imbrication — INI est plat : les sections contiennent des paires clé-valeur, pas d’autres sections
• Valeurs chaînes — toutes les valeurs sont des chaînes sauf si le parseur les convertit ; `count = 5` est la chaîne « 5 » pour la plupart des parseurs

Ce que voit le parseur

Le parseur construit une carte à deux niveaux : nom de section → clé → valeur. Si un fichier n'a pas d'en-tête de section, les valeurs se trouvent dans une section implicite « par défaut » — le `configparser` de Python l'appelle `DEFAULT`. Le fait que le parseur fusionne la section par défaut avec les sections nommées varie. Les clés et noms de section sont traités quasi universellement comme insensibles à la casse par convention, même si ce n'est pas garanti par toutes les implémentations.

Créer un fichier INI prend moins de cinq étapes. Le seul outil requis est un éditeur de texte brut — tout éditeur qui enregistre en UTF-8 ou ASCII sans marque d'ordre des octets (BOM) fonctionne correctement.

Les trois éléments structurels d'un fichier INI — sections, clés et valeurs — ont des règles et des cas limites qu'il vaut la peine de comprendre avant d'écrire une configuration qui sera lue par le parseur de quelqu'un d'autre.

Conventions de nommage des sections

Les noms de section vont entre crochets et apparaissent seuls sur leur ligne. Ils peuvent contenir des lettres, des chiffres, des espaces et la plupart des signes de ponctuation — mais les espaces dans les noms de section sont mal pris en charge par certains parseurs et doivent être évités. Utilisez `[DatabaseConfig]` ou `[database_config]` plutôt que `[database config]`. Les noms de section dupliqués sont soit fusionnés, soit provoquent une erreur selon le parseur — considérez-les comme interdits et validez avec le Validateur INI pour les détecter.

Règles de nommage des clés

Les clés ne doivent pas contenir le signe `=` ni un retour à la ligne. Au-delà, les conventions varient, mais la pratique la plus sûre consiste à n'utiliser que des lettres minuscules, des chiffres et des traits de soulignement — les mêmes règles que les noms de variables Python. Évitez les tirets dans les clés si vous comptez les lire en Python avec `configparser`, car Python renvoie les clés telles quelles et les clés avec tirets ne sont pas accessibles comme attributs.

Types de valeurs et valeurs multilignes

Toutes les valeurs des fichiers INI sont des chaînes sauf si votre parseur les convertit explicitement. `enabled = true` est la chaîne « true » — votre code doit la convertir en booléen. Le `configparser` de Python fournit les méthodes `getboolean()`, `getint()` et `getfloat()` à cet effet. Les valeurs multilignes sont prises en charge par certains parseurs (le `configparser` de Python traite les lignes commençant par des espaces comme la continuation de la valeur précédente) mais pas tous — consultez la documentation de votre parseur avant de compter dessus.

La section DEFAULT

Le `configparser` de Python traite une section nommée `[DEFAULT]` (insensible à la casse) comme une section de repli spéciale. Toute clé définie dans `[DEFAULT]` est disponible dans toutes les autres sections comme valeur de repli — si une section ne définit pas une clé, la valeur de `[DEFAULT]` est renvoyée à la place. C'est un comportement propre à Python, absent de la plupart des autres parseurs. Si vous écrivez des fichiers INI spécifiquement pour Python, `[DEFAULT]` est un moyen pratique de définir des valeurs partagées sans les répéter dans chaque section.

Les commentaires et l'encodage des caractères sont les deux aspects des fichiers INI les plus susceptibles de causer des problèmes silencieux lorsque les fichiers circulent entre outils, systèmes d'exploitation ou langages différents.

Caractères de commentaire : ; vs #

Le point-virgule (`;`) est le caractère de commentaire universellement pris en charge — il fonctionne avec le `configparser` de Python, les API natives Windows, `parse_ini_file()` de PHP, MySQL et pratiquement tout autre parseur INI. Le dièse (`#`) est pris en charge par le `configparser` de Python et la plupart des parseurs Linux, mais pas par `GetPrivateProfileString()` de Windows. Si votre fichier INI ne sera lu que par Python, l'un ou l'autre caractère est sûr. Pour des fichiers multiplateformes, utilisez exclusivement `;`.

Encodage des caractères : UTF-8 vs Windows-1252

Enregistrez les fichiers INI en UTF-8 sans BOM pour les outils modernes. Le BOM (marque d'ordre des octets, le caractère invisible `\uFEFF` au début de certains fichiers UTF-8 enregistrés par des outils Windows) pose des problèmes avec les parseurs qui le traitent comme faisant partie du premier nom de clé. Le `configparser` de Python gère l'UTF-8 nativement depuis Python 3. Si vous écrivez un fichier INI pour une application Windows héritée attendant l'encodage Windows-1252, alignez-vous sur ce que l'application attend — mélanger les encodages est une source courante de corruption de caractères dans les valeurs.

Fins de ligne

Les fichiers INI fonctionnent aussi bien avec les fins de ligne Windows (CRLF, `\r\n`) que Unix (LF, `\n`). Utilisez la convention de la plateforme cible. Si vous modifiez un fichier INI sous Windows pour un déploiement sous Linux, configurez votre éditeur pour enregistrer avec des fins de ligne LF afin d'éviter que le caractère de retour chariot n'apparaisse dans les valeurs avec les parseurs Linux. Le Formateur INI normalise les fins de ligne et l'espacement en une seule passe.

La plupart des langages fournissent un parseur intégré ou de bibliothèque standard pour les fichiers INI. Voici les approches standard pour les environnements les plus courants.

Python : configparser

Le module `configparser` de Python est la manière standard de lire les fichiers INI en Python. Importez-le, créez une instance `ConfigParser()`, appelez `.read()` avec votre nom de fichier et accédez aux valeurs avec `config["NomSection"]["clé"]` ou `config.get("NomSection", "clé")`. La méthode `.get()` accepte un argument `fallback` qui renvoie une valeur par défaut lorsque la clé est absente — utile pour les paramètres optionnels. Utilisez `getboolean()`, `getint()` et `getfloat()` pour des valeurs typées plutôt que de convertir les chaînes manuellement.

PHP : parse_ini_file()

PHP fournit `parse_ini_file($filename, $process_sections)` comme fonction intégrée. Avec `$process_sections = true`, la fonction renvoie un tableau associatif imbriqué organisé par nom de section. Avec `false`, elle renvoie un tableau plat avec toutes les clés fusionnées. Le parseur PHP est strict sur certains caractères spéciaux dans les valeurs non quotées — les valeurs contenant =, accolades ouvrante/fermante, |, &, ~, !, [, ] doivent être quotées dans le fichier INI pour être correctement analysées.

Node.js et autres environnements

Node.js n'a pas de parseur INI intégré, mais le paquet npm `ini` (licence MIT) fournit une interface standard `parse()` et `stringify()`. Pour Java, la bibliothèque `org.ini4j` est le choix standard. Pour Go, le paquet `gopkg.in/ini.v1` est l'option la plus utilisée. Dans chaque cas, la bibliothèque gère la même structure à deux niveaux section/clé — les formes d'API varient mais le format sous-jacent est identique.

INI n'est pas toujours le bon format de configuration. Comprendre où il s'inscrit — et où TOML ou YAML est un meilleur choix — vous aide à prendre la bonne décision pour vos nouveaux projets.

Quand utiliser INI

INI est le bon choix lorsque votre configuration est profonde de deux niveaux (sections et paires clé-valeur plates), lorsque le parseur cible attend déjà le format INI (PHP, écosystème Python, MySQL, Git) et lorsque vous voulez le format le plus simple possible que n'importe quel développeur puisse lire sans connaissance préalable. Il n'est pas approprié pour les configurations nécessitant des tableaux, des objets imbriqués ou des données typées.

Quand utiliser TOML ou YAML à la place

Choisissez TOML lorsque votre configuration a besoin de valeurs typées, de tableaux ou de tables en ligne et que vous voulez une spécification stricte avec un parsing prévisible. TOML est le format de `pyproject.toml`, `Cargo.toml` et des fichiers de configuration de Hugo. Choisissez YAML lorsque vous avez besoin de structures profondément imbriquées ou que vous travaillez dans un écosystème où YAML est déjà standard — Kubernetes, GitHub Actions, Docker Compose et Ansible sont tous des environnements « YAML-first ».