The INI file (.ini)

An INI file stores settings as text: section names in brackets, and under each one, lines of key = value. The name comes from "initialization": programs read the file when they start. It's easy to read and edit by hand, which is why the format has survived since the MS-DOS era.

You'll find INI files, or files in the same style with another extension, all over the place:

• Not a standard. There's no specification, so each program decides what counts as a comment, whether quotes mean anything and what happens to duplicates.
• Not typed. Every value is text. Whether false, 0 or off means "no" is up to the program.
• Not nested. Two levels, sections and keys. Anything deeper is a convention of one particular parser.

INI files became widespread with MS-DOS and 16-bit Windows. Up to Windows 3.1x, Windows itself kept its configuration in INI files such as WIN.INI and SYSTEM.INI, and programs read their own with Windows API functions like GetPrivateProfileString. Those functions look up a value by section and key, ignoring upper and lower case.

From Windows 95 and Windows NT on, Microsoft moved system settings into the registry. The INI functions still exist, but Microsoft's documentation now says they are provided only for compatibility with 16-bit applications and that applications should store settings in the registry. Windows even redirects some INI files to the registry through the IniFileMapping registry key, so editing those files has no effect.

Outside Windows the format lived on because it's so simple. Python, PHP, Git, systemd and many others adopted INI-style files, each with its own parser and its own small differences, which is where most of today's confusion comes from.

sample-parser-differences.ini contains eight ordinary-looking lines. Python's configparser, the ini package for Node.js and PHP's parse_ini_file all read it without an error, and all return something different:

Git's git config reads the first six lines (strips both inline comments and the quotes, lowercases Timeout) and then stops with bad config line, because tags[] isn't a valid Git key. The other differences that matter in practice:

• Duplicate keys. Python's configparser stops with DuplicateOptionError by default (and because it lowercases keys, Port and port count as duplicates). The ini package and PHP keep the last value. Git keeps all of them as a multi-valued key.
• Keys before the first section. configparser reports MissingSectionHeaderError unless you pass allow_unnamed_section=True (Python 3.13 and later). The ini package and PHP put them at the top level.
• Reserved words and characters in PHP. null, yes, no, true, false, on, off and none can't be keys. In unquoted values, characters such as &, |, ~ and ! have special meanings, and some, such as = and (, are syntax errors.
• Multi-line values. configparser continues a value on indented lines below it. The ini package reads those lines as new keys, and PHP ignores them.

Because there's no standard, nothing says which encoding an INI file uses. Old Windows programs read and write them in the system's ANSI code page; newer software expects UTF-8. Three things go wrong regularly:

• A byte order mark (BOM). Some Windows editors put three invisible bytes, EF BB BF, at the start of a UTF-8 file. Python's configparser, reading with encoding="utf-8", then sees \ufeff[greetings] instead of a section header and stops with MissingSectionHeaderError; reading with encoding="utf-8-sig" works. The ini package is worse: it raises no error but turns the first section header into a key, so the first section's settings end up at the top level. PHP and Git ignore the BOM.
• The wrong code page. Without an explicit encoding, Python opens the file with the system's default encoding, which on many Windows machines is not UTF-8. Accented text then comes out as é. Always pass the encoding.
• Line endings. All the parsers tested here accept Windows (CRLF) and Unix (LF) line endings.

sample-utf8-bom-crlf.ini has a BOM, CRLF line endings and non-ASCII keys and values, so you can see which of these problems a tool has.

import configparser

config = configparser.ConfigParser()
config.read("settings.ini", encoding="utf-8-sig")  # also accepts a BOM

port = config.getint("database", "port")            # "5432" -> 5432
debug = config.getboolean("app", "debug")           # "false" -> False
host = config.get("database", "host", fallback="localhost")

• Python: configparser in the standard library. Values are strings; getint(), getfloat() and getboolean() convert them, and getboolean() accepts 1/0, yes/no, true/false and on/off. Keys in a [DEFAULT] section apply to every section, and %(name)s refers to another key, which is why a literal % must be written %%.
• Node.js: the ini package. It returns true, false and null as real values, collects key[] lines into arrays and nests dotted section names.
• PHP: parse_ini_file($path, true) keeps sections. By default on, yes and true become "1"; pass INI_SCANNER_TYPED to get real booleans, null and integers.
• Windows (C, C++, C#): GetPrivateProfileString and related functions still work, case-insensitively, but Microsoft recommends the registry or a modern format for new code.
• Git-style files: git config -f file.ini section.key reads a value from any file in Git's dialect.

If you're choosing a format for a new project and like the look of INI, TOML is the closest thing with a specification: a simple INI file with # comments and quoted string values is often already valid TOML. Keep INI where a program expects it, such as php.ini or desktop.ini.

• Windows: right-click and choose Open with, then Notepad or another text editor. Some .ini files sit in protected folders such as Program Files; open the editor as administrator to save changes there.
• macOS and Linux: open it in TextEdit (in plain-text mode), VS Code or any terminal editor such as nano.
• desktop.ini: it's a hidden system file, so Explorer only shows it when "Hide protected operating system files" is turned off in Folder Options.
• php.ini: php --ini prints which file PHP loaded. After editing it, restart PHP-FPM or the web server.
• Convert to JSON: load it with a parser and write JSON, but remember the result depends on the parser, as the table above shows.

An INI file is only text and can't run anything when opened. The risk is what's written in it: INI files often hold credentials in plain text.

• Database passwords in my.cnf or an app's config.ini. Restrict who can read the file, such as chmod 600 on Linux and macOS.
• Tokens in .npmrc (registry auth tokens) and in .git/config when a remote URL includes a username and token.
• Files inside the web root. A config.ini in a public folder can be downloaded by anyone who guesses its name. Keep config files outside the folder the web server publishes, or block .ini files in the server's configuration.
• Shared copies. Before posting an INI file in a forum, ticket or link, remove passwords, keys and internal hostnames.