INI file

An INI file is a configuration file for computer software that consists of plain text with a structure and syntax comprising key–value pairs organized in sections. The name of these configuration files comes from the filename extension INI, short for initialization, used in the MS-DOS operating system which popularized this method of software configuration. The format has become an informal standard in many contexts of configuration, but many applications on other operating systems use different file name extensions, such as conf and cfg.

History

The primary mechanism of software configuration in Windows was originally a text file format that comprised text lines with one key–value pair per line, organized into sections. This format was used for operating system components, such as device drivers, fonts, and startup launchers. INI files were also generally used by applications to store individual settings.
The format was maintained in 16-bit Microsoft Windows platforms up through Windows 3.1x. Starting with Windows 95 Microsoft favored the use of the Windows Registry and began to steer developers away from using INI files for configuration. All subsequent versions of Windows have used the Windows Registry for system configuration, but applications built on the.NET Framework use special XML .config files. The initialization-file functions are still available in Windows and developers may still use them.
Besides Windows software, platform-agnostic software may use this file format for configuration. Some Unix-like config files also use a similar format. INI is human-readable and simple to parse, so it is a usable format for configuration files that do not require much greater complexity.

Prevalence

What follows is a non-exhaustive list of places in which INI files appear.

files are still used in Windows to configure properties of directories, e.g. specifying the icon for a folder.
PHP's file employs the INI format.
Git's file is written in an INI flavour.
freedesktop.org entries are written in an INI flavour.
systemd unit configuration files are written in INI.
Netatalk's file is written in an INI-style configuration language.
Pacman's file is written in INI.
Forgejo's app.ini configuration file is written in INI.
EditorConfig's .editorconfig configuration file is written in INI.
Example

The following example file has two sections: one for the owner of the software, and one for a payroll database connection. Comments record the last person who modified the file and the reason for modification.

; last modified 1 April 2001 by John Doe
name = John Doe
organization = Acme Widgets Inc.
; use IP address in case network name resolution is not working
server = 192.0.2.62
port = 143
file = "payroll.dat"

Format

In its broader sense, INI is an informal format which lends itself well to ad-hoc implementation while remaining human-configurable. Consequently, many varying specifications exist, called INI dialects.
INI interpretations depend a lot on personal taste and the needs of the computing environment, such as whitespace preservation, field type information, case sensitivity, or preferred comment delimiters. This makes INI prone to proliferation. Nonetheless, INI-flavoured implementations typically share common design features: a text file consisting of a key–value pair on each line, delimited by an equals sign, organized into sections denoted by square brackets.
In its most complicated interpretation, the INI format is able to express arbitrary S-expressions, making it equivalent to standardized formats like XML or JSON, albeit with a syntax which is not set in stone and to some may feel more comfortable.
As the INI file format is not rigidly defined, many parsers support features beyond those that form the common core. Implemented support is highly volatile. Attempts have been made to create parsers able to support as many dialects as possible.

Key–value pairs

Data in INI is held in key–value pairs called key or property. Key may thus either refer to the entire key–value pair or only its key. A value is also called property name. In its textual representation, the key–value pair is represented by either a line or a multiline where the start of the value is indicated by a delimiter, most often an equals sign but sometimes also a colon or whitespace. The key's key appears to the left of the delimiter, is often non-empty and should not contain the delimiter. Some flavours allow escape sequences in the value.
In the Windows implementation, the equals sign and the semicolon are reserved characters and cannot appear in the key. Any whitespace surrounding the key is stripped by the parser. The value can contain any character.
Key–value pairs may textually look like:

key=key=v
name =value
sem=;
semver=v5822.433.2

Sections

Key–value pairs may be grouped under a section. Some INI dialects require every key–value pair to be in a section, some allow so-called global properties. When key–value pairs are grouped, the section name appears on a line by itself, enclosed in square brackets, and applies to all key–value pairs on subsequent lines until another section is declared. There is no explicit "end of section" delimiter. Thus, sections syntactically cannot be arbitrarily nested. When required, nesting can be implemented through flattening one's hierarchy and concatenating with a custom delimiter character inside the section name. One level of nesting is often supported, called subsections.
Example INI document employing nested sections:

name = orchard rental service
target region = "Bay Area"
; TODO: advertise vacant positions
legal team =
trademark issues = foreseeable
taste = known
taste = novel
Trademark Issues="truly unlikely"
anticipated problems ="logistics "
Trademark Issues=\
possible
date = 2021-11-23, 08:54 +0900
comment = "I like red fruit."
comment: Why, \
\
\
I would buy dates.

folding: Is "\\\\\nn" interpreted as "\\n" or "\n"?
Or does "\\\\" prevent folding?

editor =My name may contain a \\
newline.

Hierarchy (section nesting)

Some parsers allow section nesting, using dots as path delimiters:

domain = example.com
foo = bar

In some cases relative nesting is supported too, where a leading dot expresses nesting to the previous section:

domain = example.com
foo = bar

Historically, ways for expressing nesting alternative to the dot have existed too. Some parsers did not offer nesting support at all and were hierarchy-blind, but nesting could still be partially emulated by exploiting the fact that constitutes a unique identifier.

Case sensitivity

Section and property names in Windows are case insensitive. Most Unix-style INI interpretations forbid case folding altogether, although case folding for the section name or key is sometimes allowed.

Comments

A line with contiguous trailing whitespace followed by a semicolon indicates a comment. Some INI dialects furthermore allow use of the number sign to denote a comment, mirroring Unix shell comments. Some INI dialects but not all allow a comment on a key–value pair line or section line, where some require whitespace separating the value or section closing bracket from the comment. The number sign might be nonetheless included in the key name in some dialects and ignored as such. Comment lines are designed to be ignored by a parser.

! /bin/convert-ini-to-perl | perl | ssh wikipedia.org upload --sanitise=no

; Ambiguous without further knowledge of the INI dialect:
; is the value "live" or "live # dangerously"?
I like to = live # dangerously

var = a

var = a ; This is an inline comment
foo = bar # This is another inline comment

Under the WinAPI's GetPrivateProfileString's dialect, comments must occur on lines by themselves.

Order of sections and properties

The order of properties in a section and the order of sections in a file is irrelevant.

Duplicate names

Most implementations only support having one property with a given name in a section. The second occurrence of a property name may cause an abort, it may be ignored, or it may override the first occurrence. Some programs use duplicate property names to implement multi-valued properties.
Interpretation of multiple section declarations with the same name also varies. In some implementations, duplicate sections simply merge their properties, as if they occurred contiguously. Others may abort, or ignore some aspect of the INI file.

Quoted values

Some implementations allow values to be quoted, typically using double quotes and/or apostrophes. This allows for explicit declaration of whitespace, and/or for quoting of special characters. The standard Windows function supports this, and will remove quotation marks that surround the values.

Line continuation

Emulating C syntax, some dialects allow line folding by a backslash as the last character on a line. In such line continuation, backslashes followed immediately by EOL cause the backslash and line break to be dropped, transforming the document's lines into logical lines.

Escape characters

Some dialects offer varying support for character escaping, typically with the backslash character as a metacharacter and emulating C syntax.
It is not wise to blindly interpret escape sequences as some specifications explicitly mute their metacharacter for common escape sequences.

Sequence	Meaning
`\\`	\
`\'`	Apostrophe
`\"`	Double quotes
`\0`	Null character
`\a`	Bell/Alert/Audible
`\b`	Backspace, Bell character for some applications
`\t`	Tab character
`\r`	Carriage return
`\n`	Line feed
`\;`	Semicolon
`\#`	Number sign
`\=`	Equals sign
`\:`	Colon
`\xhhhh`	Unicode character with code point 0xhhhh, encoded either in UTF-8 or local encoding