Guide

INI Configuration Files: Structure, Parsers, and Best Practices

PC By Pablo Cirre • Updated May 7, 2026

INI Files: The Enduring Configuration Standard

INI files are one of computing's most resilient formats. Originally popularized by Microsoft Windows in the 1980s, the .ini extension has outlasted dozens of competing configuration standards and remains in active use across operating systems, programming languages, and embedded systems. Their staying power comes from an almost brutal simplicity: plain text, human-readable, no required schema, no parser installation.

Anatomy of an INI File

The INI format defines four structural elements:

Sections group related settings under a bracketed header:

[database]
host = localhost
port = 5432
name = myapp

Key-value pairs use = or : as the delimiter depending on the parser. Whitespace around the delimiter is typically ignored:

timeout = 30
max_connections=100
retry_delay : 5

Comments begin with ; (traditional) or # (Unix convention). Many parsers accept both:

; This is a traditional comment
# This is a Unix-style comment
host = localhost  ; inline comments work in some parsers

Global keys (before any section) are supported by most parsers and fall into an implicit default namespace.

What the Format Does NOT Define

The INI specification is deliberately loose — there is no single authoritative RFC. Implementations differ on:

Whether key names are case-sensitive (Host ≠ host in some parsers)
Multiline values — some parsers require a trailing backslash continuation; others use indentation
Quoted strings — name = "John Doe" may or may not strip quotes
Nested sections — Windows-style [section.subsection] is not universally supported
Duplicate keys — last-wins vs. first-wins vs. error depending on the library
Boolean values — true/false, yes/no, 1/0, on/off are all used across different systems

This flexibility makes INI portable but requires knowing which dialect your parser speaks.

Platform and Language Prevalence

Windows: The Win32 API includes GetPrivateProfileString() / WritePrivateProfileString() for reading and writing INI files. Windows itself uses INI files for win.ini, system.ini, and countless application settings stored in %APPDATA%.

Python: The configparser module in the standard library reads INI files natively. It supports sections, fallback values, interpolation (%(key)s syntax), and multiline values:

import configparser
config = configparser.ConfigParser()
config.read('settings.ini')
db_host = config['database']['host']
db_port = config.getint('database', 'port')

PHP: parse_ini_file() is a built-in function that returns a nested array. The INI_SCANNER_TYPED flag automatically converts boolean strings and integers.

Java: No standard library support, but java.util.Properties handles a similar flat key=value format without sections.

.NET: Microsoft.Extensions.Configuration reads INI files via AddIniFile() in modern ASP.NET Core apps.

Linux/Unix: Desktop applications often prefer INI-style files for configuration (GNOME's GLib GKeyFile, KDE's KConfig). Many /etc/ configuration files use INI syntax.

Common Use Cases

Application settings: Database credentials, API endpoints, feature flags, UI preferences — anything that needs to be configurable without recompiling.

Game configuration: Many games store graphics settings, key bindings, and difficulty options in INI files. The Unreal Engine uses extensive INI hierarchies (BaseGame.ini, DefaultEngine.ini, platform-specific overrides).

Tool configuration: pytest uses pytest.ini or a [pytest] section in setup.cfg. Flake8 reads from setup.cfg or .flake8. MySQL reads my.ini / my.cnf on startup.

Localization: Some older applications store translation strings as INI key-value pairs, one file per language.

Converting and Processing INI Files

INI to JSON: Useful when integrating with APIs or JavaScript front-ends. Python's configparser + json.dumps() does this in a few lines. The challenge is that INI sections become JSON object keys:

{
  "database": {"host": "localhost", "port": "5432"},
  "cache": {"driver": "redis", "ttl": "3600"}
}

INI to TOML: TOML is often considered the modern, typed successor to INI. The structure maps almost directly — TOML adds types, arrays, and inline tables. Tools like ini2toml automate migration.

INI to YAML: YAML allows deeper nesting and typed values. Many DevOps pipelines prefer YAML for infrastructure configuration.

Merging multiple INI files: Configuration hierarchies often work by layering files (global defaults → user overrides → environment-specific). Python's configparser.read([...]) merges multiple files, with later files overriding earlier ones.

Security Considerations

INI files containing credentials should never be committed to version control. Common patterns to protect them:

Add *.ini or the specific filename (e.g., config.ini) to .gitignore
Use environment variable substitution where the parser supports it
Store secrets in dedicated secret managers and load them at runtime rather than hardcoding in files
Set restrictive file permissions: chmod 600 config.ini on Unix systems

Encoding and Character Sets

INI files are plain text and typically ASCII or UTF-8. The Windows API historically used system ANSI encoding (CP1252 on Western systems), which can cause issues with non-ASCII characters when files are shared across systems. Always specify UTF-8 explicitly or use BOM-aware parsers when dealing with multilingual content.

INI vs. Modern Alternatives

Feature	INI	TOML	YAML	JSON
Human readable	✅	✅	✅	Moderate
Typed values	❌ (strings only)	✅	✅	✅
Comments	✅	✅	✅	❌
Arrays	Limited	✅	✅	✅
Deep nesting	❌	✅	✅	✅
Whitespace sensitive	❌	❌	✅	❌
Standard spec	❌	✅	✅	✅

INI wins on simplicity and ubiquity. For hierarchical structured data, TOML or YAML offer richer semantics. For machine-to-machine exchange, JSON is usually preferred.

Practical Tips

Use a real parser instead of custom regex splitting. Edge cases like quoted values, inline comments, and continuation lines will break naïve implementations.
Document your dialect in a comment at the top of the file — note which parser/library reads it and what syntax features it supports.
Keep sections flat — INI's one-level hierarchy is a feature, not a bug. If your config needs deep nesting, consider switching to TOML or YAML.
Validate on load — assert required keys exist and fall back to documented defaults rather than silently using empty values.
Version your config format — add a version = 2 key so applications can handle format migrations gracefully.

Despite their age, INI files remain an excellent choice for simple, human-editable configuration where an 80-character plain text file beats an XML schema or a YAML parser dependency.

Related conversions

Frequent conversions across the catalogue:

Frequently Asked Questions

Both are used for comments but come from different traditions. The semicolon (;) is the original Windows INI convention, while the hash (#) follows Unix shell practice. Not all parsers accept both — Python's configparser accepts either by default, but strict Windows-era parsers may only recognize semicolons. Check your parser's documentation and stick to one style per project.

Both are used para comments mas come de different traditions. The semicolon (;) is the original Windows INI convention, while the hash (#) follows Unix shell practice. Not all parsers accept both — Python's configparser accepts either by default, mas strict Windows-era parsers may only recognize semicolons. Check your parser's documentation e stick to one style per project.

Both are used für comments aber come von different traditions. The semicolon (;) is the original Windows INI convention, while the hash (#) follows Unix shell practice. Not all parsers accept both — Python's configparser accepts either by default, aber strict Windows-era parsers may only recognize semicolons. Check your parser's documentation und stick to one style per project.

Both are used para comments pero come de different traditions. The semicolon (;) is the original Windows INI convention, while the hash (#) follows Unix shell practice. Not all parsers accept both — Python's configparser accepts either by default, pero strict Windows-era parsers may only recognize semicolons. Check your parser's documentation y stick to one style per project.

On KaijuConverter every file is processed inside an isolated container, encrypted in transit (TLS 1.3) and at rest, and automatically deleted after 60 minutes with multi-pass overwrite. We never train on, share, or analyze user content. For maximum privacy on extremely sensitive material, prefer offline tools (ImageMagick, FFmpeg, LibreOffice) that you control end-to-end.

Standard INI has no native array syntax. Common workarounds include numbered keys (item1=, item2=, item3=), a comma-separated string you split yourself, or repeating the same key when the parser supports last-wins or multi-value semantics. If you need real arrays, consider TOML ([array.of.tables]) or YAML lists instead.

Standard INI has no native array syntax. Common workarounds include numbered keys (item1=, item2=, item3=), a comma-separated string you split yourself, ou repeating the same key when the parser suporta last-wins ou multi-value semantics. If you need real arrays, consider TOML ([array.of.tables]) ou YAML lists instead.

Standard INI has no native array syntax. Common workarounds include numbered keys (item1=, item2=, item3=), a comma-separated string you split yourself, oder repeating the same key when the parser unterstützt last-wins oder multi-value semantics. If you need real arrays, consider TOML ([array.of.tables]) oder YAML lists instead.

Standard INI has no native array syntax. Common workarounds include numbered keys (item1=, item2=, item3=), a comma-separated string you split yourself, o repeating the same key when the parser soporta last-wins o multi-value semantics. If you need real arrays, consider TOML ([array.of.tables]) o YAML lists instead.

For 95% of use cases, yes — server-side ImageMagick, FFmpeg and LibreOffice produce identical output to the same tools on your laptop. Desktop software wins for: extremely large files (multi-GB), batch jobs of thousands of files, scripted pipelines, or content too sensitive to upload. KaijuConverter caps at 25 MB per file on the free tier (up to 2 GB on paid plans).

It depends on the parser. Python's configparser lowercases all key names by default (making them case-insensitive), while many C and Windows parsers treat them case-sensitively. Always test with your target parser and use consistent casing to avoid cross-platform surprises.

Most format conversions are lossy by design — JPG, MP3, MP4, WebP all discard perceptual data to save bytes. Going through a lossy intermediate compounds the loss. To minimize visible/audible drift: convert from the original master, choose a higher quality setting, and avoid converting back and forth between lossy formats.

Most parsers support multiline values via indentation — subsequent lines that start with whitespace are treated as continuation of the previous value. Python's configparser handles this automatically. Some parsers also support a trailing backslash (\) continuation. The specific syntax depends on your parser; check its documentation for the exact multiline mechanism.

Yes — KaijuConverter accepts multiple files in a single drop and returns a ZIP. For very large batches (thousands of files) consider command-line tools or our API: <code>find . -name "*.heic" -exec magick {} {.}.jpg \;</code> or similar one-liners scale to millions of files when run locally.