So erstellen Sie eine INI-Datei: Syntaxregeln, Abschnitte und Parser

Eine INI-Datei ist eine Klartext-Konfigurationsdatei, die Einstellungen als Schlüssel-Wert-Paare speichert, optional gruppiert in benannte Abschnitte. Der Name kommt von „Initialisierung“ – INI-Dateien wurden verwendet, um Windows-Anwendungen mit ihren Einstellungen zu initialisieren, bevor es die Windows-Registrierung gab. Das Format hatte nie eine formale Spezifikation, aber ein faktischer Standard entstand durch die weitverbreitete Nutzung.

Wo INI-Dateien heute verwendet werden

• Python-Paketierung – `setup.cfg`, `tox.ini`, `pytest.ini`, `mypy.ini`, `.flake8`
• PHP-Laufzeit – `php.ini` steuert global die Einstellungen des PHP-Interpreters
• MySQL / MariaDB – `my.ini` (Windows) und `my.cnf` (Unix) konfigurieren den Datenbankserver
• Git – `.gitconfig` und `.git/config` verwenden ein INI-ähnliches Format für Repository- und Benutzereinstellungen
• Wine – `wine.inf` konfiguriert die Windows-Kompatibilitätsschicht unter Linux und macOS
• Windows-Anwendungen – Tausende ältere und moderne Desktop-Apps speichern Einstellungen in `.ini`-Dateien im AppData-Ordner

INI vs. die Windows-Registrierung

Microsoft verlagerte die Einstellungen von Windows-Anwendungen Anfang der 1990er Jahre in die Registrierung, aus Gründen der Performance und zentralisierten Verwaltung. Viele Entwickler ziehen INI-Dateien jedoch weiterhin wegen der Portabilität vor – eine INI-Datei kann mit jedem Texteditor eingesehen und bearbeitet, in die Versionskontrolle eingecheckt und zwischen Maschinen kopiert werden, ganz ohne Export-/Import-Tools. Die Registrierung kann das nicht.

Trotz fehlender formaler Spezifikation folgt die INI-Syntax in praktisch allen Parsern konsistenten Konventionen. Dies sind die Regeln, auf die Sie sich verlassen können, unabhängig davon, was Ihre Datei liest.

Eine INI-Datei ist das denkbar einfachste Konfigurationsformat: Abschnitte in Klammern, darunter Schlüssel-Wert-Paare und Semikolons für Kommentare. Alles andere ist parserspezifisch.

Universelle Regeln

• Ein Schlüssel-Wert-Paar pro Zeile – `key = value` oder `key=value`; das Leerzeichen um `=` ist optional, aber konsistenter Abstand ist lesbar
• Abschnittsüberschriften – `[Abschnittsname]` allein auf einer Zeile; kein Inhalt nach der schließenden Klammer
• Kommentarzeilen – beginnen Sie mit `;` für maximale Kompatibilität; `#` wird von einigen Parsern unterstützt (Python `configparser`, Linux-Tools), aber nicht von Windows-nativen APIs
• Leerzeilen – werden von allen Parsern ignoriert; verwenden Sie sie frei, um logische Gruppen innerhalb eines Abschnitts zu trennen
• Keine Verschachtelung – INI ist flach: Abschnitte enthalten Schlüssel-Wert-Paare, nicht andere Abschnitte
• Zeichenkettenwerte – alle Werte sind Zeichenketten, sofern der Parser sie nicht konvertiert; `count = 5` ist für die meisten Parser die Zeichenkette „5“

Was der Parser sieht

Der Parser baut eine zweistufige Map auf: Abschnittsname → Schlüssel → Wert. Hat eine Datei keine Abschnittsüberschriften, liegen die Werte in einem impliziten „Standard“-Abschnitt – Pythons `configparser` nennt ihn `DEFAULT`. Ob der Parser den Standardabschnitt mit benannten Abschnitten verschmilzt, variiert. Schlüssel und Abschnittsnamen werden fast überall per Konvention als case-insensitive behandelt, auch wenn das nicht von allen Implementierungen garantiert wird.

Eine INI-Datei zu erstellen dauert weniger als fünf Schritte. Das einzige benötigte Werkzeug ist ein einfacher Texteditor – jeder Editor, der als UTF-8 oder ASCII ohne Byte-Order-Mark (BOM) speichert, funktioniert korrekt.

Die drei Strukturelemente einer INI-Datei – Abschnitte, Schlüssel und Werte – haben Regeln und Randfälle, die es zu verstehen lohnt, bevor Sie eine Konfiguration schreiben, die vom Parser einer anderen Person gelesen wird.

Namenskonventionen für Abschnitte

Abschnittsnamen stehen in eckigen Klammern und erscheinen auf einer eigenen Zeile. Sie dürfen Buchstaben, Zahlen, Leerzeichen und die meisten Satzzeichen enthalten – aber Leerzeichen in Abschnittsnamen werden von einigen Parsern schlecht unterstützt und sollten vermieden werden. Verwenden Sie `[DatabaseConfig]` oder `[database_config]` statt `[database config]`. Doppelte Abschnittsnamen werden je nach Parser zusammengeführt oder erzeugen einen Fehler – behandeln Sie sie als verboten und validieren Sie mit dem INI-Validator, um Duplikate zu erkennen.

Regeln für Schlüsselnamen

Schlüssel dürfen weder das `=`-Zeichen noch einen Zeilenumbruch enthalten. Darüber hinaus variieren die Konventionen, aber die sicherste Praxis ist, nur Kleinbuchstaben, Ziffern und Unterstriche zu verwenden – dieselben Regeln wie bei Python-Variablennamen. Vermeiden Sie Bindestriche in Schlüsseln, wenn Sie sie in Python mit `configparser` lesen wollen, da Python die Schlüssel unverändert zurückgibt und Schlüssel mit Bindestrich nicht als Attribute zugreifbar sind.

Werttypen und mehrzeilige Werte

Alle Werte in INI-Dateien sind Zeichenketten, sofern Ihr Parser sie nicht explizit konvertiert. `enabled = true` ist die Zeichenkette „true“ – Ihr Code muss sie in einen Booleanschen Wert umwandeln. Pythons `configparser` bietet dafür die Methoden `getboolean()`, `getint()` und `getfloat()`. Mehrzeilige Werte werden von einigen Parsern unterstützt (Pythons `configparser` behandelt Zeilen mit führenden Leerzeichen als Fortsetzung des vorigen Werts), aber nicht von allen – prüfen Sie die Dokumentation Ihres Parsers, bevor Sie sich darauf verlassen.

Der DEFAULT-Abschnitt

Pythons `configparser` behandelt einen Abschnitt namens `[DEFAULT]` (Groß-/Kleinschreibung egal) als speziellen Fallback-Abschnitt. Jeder in `[DEFAULT]` definierte Schlüssel ist in allen anderen Abschnitten als Fallback verfügbar – definiert ein Abschnitt einen Schlüssel nicht, wird stattdessen der Wert aus `[DEFAULT]` zurückgegeben. Dies ist ein Python-spezifisches Verhalten, das in den meisten anderen Parsern nicht existiert. Wenn Sie INI-Dateien speziell für Python schreiben, ist `[DEFAULT]` ein praktischer Weg, geteilte Werte zu definieren, ohne sie in jedem Abschnitt zu wiederholen.

Kommentare und Zeichenkodierung sind die zwei Aspekte von INI-Dateien, die am ehesten stille Probleme verursachen, wenn Dateien über verschiedene Tools, Betriebssysteme oder Programmiersprachen hinweg geteilt werden.

Kommentarzeichen: ; vs. #

Das Semikolon (`;`) ist das universell unterstützte Kommentarzeichen – es funktioniert in Pythons `configparser`, in Windows-nativen APIs, in PHPs `parse_ini_file()`, in MySQL und in praktisch jedem anderen INI-Parser. Die Raute (`#`) wird von Pythons `configparser` und den meisten Linux-Parsern unterstützt, aber nicht von Windows’ `GetPrivateProfileString()`. Wenn Ihre INI-Datei jemals nur von Python gelesen wird, ist beides sicher. Für plattformübergreifende Dateien verwenden Sie ausschließlich `;`.

Zeichenkodierung: UTF-8 vs. Windows-1252

Speichern Sie INI-Dateien für moderne Tools als UTF-8 ohne BOM. Das BOM (Byte-Order-Mark, das unsichtbare `\uFEFF`-Zeichen am Anfang mancher von Windows-Tools gespeicherter UTF-8-Dateien) bereitet Problemen mit Parsern, die es als Teil des ersten Schlüsselnamens behandeln. Pythons `configparser` verarbeitet UTF-8 seit Python 3 nativ. Wenn Sie eine INI-Datei für eine ältere Windows-Anwendung schreiben, die Windows-1252-Kodierung erwartet, richten Sie sich nach der Anwendung – gemischte Kodierungen sind eine häufige Quelle für Zeichencorruption in Werten.

Zeilenenden

INI-Dateien funktionieren sowohl mit Windows- (CRLF, `\r\n`) als auch Unix-Zeilenenden (LF, `\n`). Verwenden Sie die Konvention der Zielplattform. Wenn Sie eine INI-Datei unter Windows bearbeiten, die unter Linux deployed wird, stellen Sie Ihren Editor auf LF-Zeilenenden ein, damit das Wagenrücklaufzeichen nicht in Werten auf Linux-Parsern auftaucht. Der INI-Formatter normalisiert Zeilenenden und Abstände in einem Durchgang.

Die meisten Sprachen bieten einen integrierten oder Standardbibliotheks-Parser für INI-Dateien. Hier sind die Standardansätze für die gängigsten Umgebungen.

Python: configparser

Pythons Modul `configparser` ist der Standardweg, INI-Dateien in Python zu lesen. Importieren Sie es, erstellen Sie eine `ConfigParser()`-Instanz, rufen Sie `.read()` mit Ihrem Dateinamen auf und greifen Sie auf Werte mit `config["Abschnittsname"]["schlüssel"]` oder `config.get("Abschnittsname", "schlüssel")` zu. Die Methode `.get()` akzeptiert ein `fallback`-Argument, das bei fehlendem Schlüssel einen Standardwert zurückgibt – nützlich für optionale Konfigurationswerte. Verwenden Sie `getboolean()`, `getint()` und `getfloat()` für typisierte Werte, statt Strings manuell zu casten.

PHP: parse_ini_file()

PHP bietet `parse_ini_file($filename, $process_sections)` als eingebaute Funktion. Mit `$process_sections = true` gibt die Funktion ein verschachteltes assoziatives Array zurück, nach Abschnittsnamen organisiert. Mit `false` gibt sie ein flaches Array mit allen verschmolzenen Schlüsseln zurück. Der PHP-Parser ist streng bei bestimmten Sonderzeichen in nicht quotierten Werten – Werte mit =, öffnende/schließende Klammern, |, &, ~, !, [, ] müssen in der INI-Datei in Anführungszeichen stehen, um korrekt geparst zu werden.

Node.js und andere Umgebungen

Node.js hat keinen integrierten INI-Parser, aber das npm-Paket `ini` (MIT-Lizenz) bietet eine standardmäßige `parse()`- und `stringify()`-Schnittstelle. Für Java ist `org.ini4j` die Standardwahl. Für Go ist das Paket `gopkg.in/ini.v1` die am weitesten verbreitete Option. In jedem Fall verarbeitet die Bibliothek dieselbe zweistufige Abschnitt/Schlüssel-Struktur – die API-Formen variieren, aber das zugrunde liegende Format ist identisch.

INI ist nicht immer das richtige Konfigurationsformat. Zu verstehen, wo es passt – und wo TOML oder YAML die bessere Wahl ist – hilft Ihnen, für neue Projekte die richtige Entscheidung zu treffen.

Wann Sie INI verwenden

INI ist die richtige Wahl, wenn Ihre Konfiguration zwei Ebenen tief ist (Abschnitte und flache Schlüssel-Wert-Paare), wenn der Ziel-Parser bereits INI erwartet (PHP, Python-Ökosystem, MySQL, Git) und wenn Sie das denkbar einfachste Format wollen, das jeder Entwickler ohne Vorwissen lesen kann. Nicht geeignet ist es für Konfigurationen, die Arrays, verschachtelte Objekte oder typisierte Daten benötigen.

Wann Sie stattdessen TOML oder YAML verwenden

Wählen Sie TOML, wenn Ihre Konfiguration typisierte Werte, Arrays oder Inline-Tabellen braucht und Sie eine strenge Spezifikation mit vorhersagbarem Parsing wünschen. TOML ist das Format für `pyproject.toml`, `Cargo.toml` und Hugos Konfigurationsdateien. Wählen Sie YAML, wenn Sie tief verschachtelte Strukturen brauchen oder in einem Ökosystem arbeiten, in dem YAML bereits Standard ist – Kubernetes, GitHub Actions, Docker Compose und Ansible sind allesamt YAML-first-Umgebungen.