INI file

An INI file is a configuration file for computer software that consists of a text-based content with a structure and syntax comprising key–value pairs for properties, and sections that organize the properties.^[1] The name of these configuration files comes from the filename extension INI, 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.^[2]

INI

Filename extension	.ini
Internet media type	text/plain, application/textedit, zz-application/zz-winassoc-ini
Type of format	Initialization/Configuration File

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.^[3]

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.

• Desktop.ini files are still used in Windows to configure properties of directories, e.g. specifying the icon for a folder. ^[4][5]
• PHP's php.ini file employs the .INI format.^[6][7]
• Git's .git/config file is written in an .INI flavour.^[8]
• freedesktop.org *.desktop desktop entries are written in an .INI flavour.^[9]
• systemd *.service unit configuration files are written in .INI.^[10]
• Netatalk's afp.conf file is written in an .INI-style configuration language.^[11]
• Pacman's pacman.conf file is written in .INI.^[12]

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 [owner] name = John Doe organization = Acme Widgets Inc. [database] ; 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 (where sometimes a parser implementation is the only specification ever written) exist, called .INI dialects.

Whilst .INI interpretations depend a lot on personal taste and computing environment (e.g.: the need for whitespace-exact data; the need for field type information; Windows preferring case folding, Unix preferring case sensitivity; #-demarcated comments being borrowed from Unix scripting), thus making .INI prone to proliferation, a hard core exists with which .INI-flavoured is typically associated: text-based and line-based, whitespace is stripped, empty lines and comment lines (e.g. ; registers to system-wide mailcap, # workaround for d5cb328) are ignored, square brackets denoting sections (e.g. [Unit], [branch "master"]), data as key-value pairs often demarcated with an equals sign (ASCII 0x3D) (e.g. IconFile=Folder.ico, time machine = yes).

Attempts to create parsers able to support as many dialects as possible exist,^[13] and in its most complicated interpretation, the .INI format is able to express arbitrary S-expressions, making it equivalent to standardised 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.

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 (=, ASCII 0x3D) but sometimes also a colon (:, ASCII 0x3A) or whitespace (occasionally used in the GNU world^[13]). 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 (in Windows-style, no whitespace surrounds the delimiter: e.g. IconFile=Folder.ico).

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.^[14] When key-value pairs are grouped, the section name appears on a line by itself, enclosed in square brackets ([, ASCII 0x5B, and ], ASCII 0x5D), and applies to all key-value pairs on subsequent lines until another section is declared. There is no explicit "end of section" delimiter (such as e.g. XML's </tag>. 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 (often ., ASCII 0x2E). One level of nesting is often supported, called subsections.

Exemplary .INI document employing nested sections:

[project] name = orchard rental service (with app) target region = "Bay Area" ; TODO: advertise vacant positions legal team = (vacant) [fruit "Apple"] trademark issues = foreseeable taste = known [fruit.Date] taste = novel Trademark Issues="truly unlikely" [fruit "Raspberry"] anticipated problems ="logistics (fragile fruit)" Trademark Issues=\  possible [fruit.raspberry.proponents.fred] date = 2021-11-23, 08:54 +0900 comment = "I like red fruit." [fruit "Date/proponents/alfred"] 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:

[section] domain = example.com [section.subsection] foo = bar 

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

[section] domain = example.com [.subsection] foo = bar 

Historically, ways for expressing nesting alternative to the dot have existed too (for example, IBM's driver file for Microsoft Windows devlist.ini, in which the backslash was used as nesting delimiter in the form of [A\B\C]; or Microsoft Visual Studio's AEMANAGR.INI file, which used a completely different syntax in the form of [A] and B,C,P = V). 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 [A.B.C] constitutes a unique identifier.

Case sensitivity

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

Comments

A line with contiguous trailing whitespace followed by a semicolon (;, ASCII 0x3E) indicates a comment. Some .INI dialects furthermore allow use of the number sign (#, ASCII 0x23) 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 (called in-line comment), 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 (and the value discarded), or it may override the first occurrence (with the first value discarded). 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 (equals, semicolon, etc.). The standard Windows function GetPrivateProfileString supports this, and will remove quotation marks that surround the values.

Line continuation

Emulating C syntax, some dialects allow line folding by a backslash (\, ASCII 0x5C) as the last character on a line.^[18] In such line continuation, backslashes followed immediately by EOL (end-of-line) 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 (\, ASCII 0x5C) as a metacharacter and emulating C syntax.^[19]

It is not wise to blindly interpret escape sequences as some specifications explicitly mute their metacharacter for common escape sequences.^[20][21]

Common escape sequences

Sequence	Meaning
\\	\ (a single backslash, escaping the escape character)
\'	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

Accessing INI files

Under Windows, the Profile API is the programming interface used to read and write settings from classic Windows .ini files. For example, the GetPrivateProfileString function retrieves a string from the specified section in an initialization file. (The "private" profile is contrasted with GetProfileString, which fetches from WIN.INI.)

The following sample C program demonstrates reading property values from the above sample INI file (let the name of configuration file be dbsettings.ini):

#include <windows.h>  int main(int argc, _TCHAR *argv[]) {  _TCHAR dbserver[1000];  int dbport;  GetPrivateProfileString("database", "server", "127.0.0.1", dbserver, sizeof(dbserver) / sizeof(dbserver[0]), ".\\dbsettings.ini");  dbport = GetPrivateProfileInt("database", "port", 143, ".\\dbsettings.ini");  // N.B. WritePrivateProfileInt() does not exist, only WritePrivateProfileString()  return 0; } 

The third parameter of the GetPrivateProfileString function is the default value, which are "127.0.0.1" and 143 respectively in the two function calls above. If the argument supplied for this parameter is NULL, the default is an empty string, "".

Under Unix, many different configuration libraries exist to access INI files. They are often already included in frameworks and toolkits. Examples of INI parsers for Unix include GLib, iniparser and libconfini.

Comparison of INI parsers

Name	Sections support	Section nesting support	Disabled entry recognition^[22]	Multi-line support^[23]	Value types	Read/Write support	Platform	License	Programming language	Latest release version
Python ConfigParser^[24]^[25]	Yes	Yes	No	Non-standard^[26]	Boolean, Number, String	Read + Write	*BSD, Linux, macOS, Windows	PSFL	C (implementation), Python (usage)	3.9.7^[27]
GLib^[28]	Yes	Yes	No	No	Boolean, Number, String, Array	Read + Write	*BSD, Linux, macOS, Windows	LGPL	C	2.66.7 (February 11, 2021; 3 years ago (2021-02-11)) [±]^[29] ^[30]
inifile^[31]	Yes	No	No	No	Boolean, Number, String	Read + Write	*BSD, Linux, macOS, Windows	Apache	Go	1.2.0^[32]
inih^[33]	Yes	No	No	Non-standard^[34]	Boolean, Number, String	Read	*BSD, Linux, macOS, Windows	BSD	C	53^[35]
iniparser^[36]	Yes	No	No	Yes	Boolean, Number, String	Read + Write	*BSD, Linux, macOS, Windows	MIT	C	4.1^[37]
Java (via java.util.Properties)^[38]	No	No	No	Yes	String	Read + Write	Platform-agnostic	Dual-license: GPL version 2 with classpath exception,^[39] and a proprietary license.^[40]	C (implementation), Java (usage)	22.0.1 (April 19, 2024; 12 days ago (2024-04-19)) [±] 21.0.0 LTS (September 19, 2023; 7 months ago (2023-09-19)) [±] 17.0.6 LTS (February 18, 2023; 14 months ago (2023-02-18)) [±] 11.0.17 LTS (October 18, 2022; 18 months ago (2022-10-18)^[41]) [±] 8u401 LTS (January 16, 2024; 3 months ago (2024-01-16)^[42]) [±]
libconfini^[43]	Yes	Yes	Yes	Yes	Boolean, Number, String, Array	Read	*BSD, Linux, macOS, Windows	GPL	C	1.16.2^[44]
PHP (via parse_ini_file())^[45]	Yes	Yes	Yes	No	Number, String, Null	Read	Linux, macOS, Windows	PHP License v3.01^[46]	C (implementation), PHP (usage)	8.3.6^[47]   (11 April 2024; 20 days ago (11 April 2024))
PyINI^[48]	Yes	No	Yes	Yes	Boolean, Number, String	Read + Write	Platform-agnostic	GPL	Python	1.0^[49]
python-ini^[50]	Yes	No	No	Yes	Boolean, Number, String, Null	Read + Write	Platform-agnostic	BSD	Python	1.1.0
RudeConfig^[51]	Yes	No	No	No	Boolean, Number, String	Read + Write	Linux, Windows	GPL	C++	Discontinued – last version is 5.0.5, from November 2009^[52]
Windows API	Yes	No	No	No	Number, String, Struct	Read + Write (non-destructive)	Windows	Proprietary	C	23H2 (10.0.22631.3527) (April 23, 2024; 8 days ago (2024-04-23)^[53]) [±]
Wine (implementation of Windows API)	Yes	No	No	No	Number, String, Struct	Read + Write (non-destructive)	Linux, macOS, Windows	LGPL	C	9.0^[54]   16 January 2024; 3 months ago (16 January 2024)
Rust configparser^[55]	Yes	No	No	No	Boolean, Number, String	Read + Write	*BSD, Linux, macOS, Windows	MIT or LGPL v3.0+	Rust	3.0.2^[55] 11 September 2022; 3 months ago
java-ini-parser^[56]	Yes	No	Yes	Yes	Boolean, Number, String	Read + Write	Platform-agnostic	Apache	Java	1.4^[55] 29 December 2022; 3 days ago
Name	Sections support	Section nesting support	Disabled entry recognition	Multi-line support	Value types	Read/Write support	Platform	License	Programming language	Latest release version

File mapping

Initialization file mapping creates a mapping between an INI file and the Windows registry.^[57][58] It was introduced with Windows NT and Windows 95 as a way to migrate from storing settings in classic .ini files to the new registry. File mapping traps the Profile API calls and, using settings from the IniFileMapping Registry section, directs reads and writes to appropriate places in the Registry.

Using the example below, a string call could be made to fetch the name key from the owner section from a settings file called, say, dbsettings.ini. The returned value should be the string "John Doe":

GetPrivateProfileString("owner", "name", ... , "c:\\programs\\oldprogram\\dbsettings.ini"); 

INI mapping takes this Profile API call, ignores any path in the given filename and checks to see if there is a Registry key matching the filename under the directory:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\IniFileMapping

If this exists, it looks for an entry name matching the requested section. If an entry is found, INI mapping uses its value as a pointer to another part of the Registry. It then looks up the requested INI setting in that part of the Registry.

If no matching entry name is found and there is an entry under the (Default) entry name, INI mapping uses that instead. Thus each section name does not need its own entry.

HKEY_LOCAL_MACHINE\Software\...\IniFileMapping\dbsettings.ini
(Default)	@USR:Software\oldprogs\inisettings\all
database	USR:Software\oldprogs\inisettings\db

So, in this case the profile call for the [owner] section is mapped through to:

HKEY_CURRENT_USER\Software\oldprogs\inisettings\all
name	John Doe
organization	Acme Products

where the "name" Registry entry name is found to match the requested INI key. The value of "John Doe" is then returned to the Profile call. In this case, the @ prefix on the default prevents any reads from going to the dbsettings.ini file on disk. The result is that any settings not found in the Registry are not looked for in the INI file.

The "database" Registry entry does not have the @ prefix on the value; thus, for the [database] section only, settings in the Registry are taken first followed by settings in the dbsettings.ini file on disk.

Alternatives

Starting with Windows 95, Microsoft began strongly promoting the use of the Windows registry over INI files.^[59] INI files are typically limited to two levels (sections and properties) and do not handle binary data well. This decision, however, has not been immune to critiques, due to the fact that the registry is monolithic, opaque and binary, must be in sync with the filesystem, and represents a single point of failure for the operating system.^[60]

Later XML-based configuration files became a popular choice for encoding configuration in text files.^{[citation needed]} XML allows arbitrarily complex levels and nesting, and has standard mechanisms for encoding binary data.

More recently, data serialization formats, such as JSON, TOML, and YAML can serve as configuration formats. These three alternative formats can nest arbitrarily, but have a different syntax than the INI file. Among them, TOML most closely resembles INI, but the idea to make TOML deliberately compatible with a large subset of INI was rejected.^[61]

The newest INI parsers however allow the same arbitrary level of nesting of XML, JSON, TOML, and YAML, offer equivalent support of typed values and Unicode, although keep the "informal status" of INI files by allowing multiple syntaxes for expressing the same thing.^[62]

See also

• BOOT.INI
• MSConfig
• Sysedit
• SYSTEM.INI
• TOML, a very similar but more formally-specified configuration file format
• WIN.INI
• Amiga's IFF files
• .DS_Store
• .properties

References

1. Microsoft TechNet: Configure an Ini File Item
2. .conf initialization files
3. Microsoft: Windows NT Workstation Resource Kit
4. Microsoft Learn (2022-02-08). "How to Customize Folders with Desktop.ini". Retrieved 2024-01-10.
5. Codrut Neagu, "Why Are There Two Desktop.ini Files On My Desktop & What Do They Do?".
6. Rasmus Lerdorf, Kevin Tatroe, Peter MacIntyre. "Programming PHP". Sections "parse_ini_file", "Extension INI Entries", etc.
7. Christian Wenz. "PHP and MySQL Phrasebook". section "Parsing INI Files". quote: "... the INI file format ... was very widely used in the Windows world, but today also drives the configuration of software products like PHP. For instance, ... php.ini"
8. "git-config CONFIGURATION FILE".
9. "Basic format of the file". specifications.freedesktop.org.
10. "systemd.service". www.freedesktop.org.
11. "afp.conf — Netatalk configuration file". Retrieved 2024-01-10.
12. "pacman.conf(5)". archlinux.org.
13. libconfini's Library Function Manual
14. Apache Documentation for org.apache.commons.configuration2.INIConfiguration, The Apache Software Foundation
15. This includes the Windows implementation. See "GetPrivateProfileString function". Microsoft Developer Network. Microsoft. Retrieved 2012-06-02.
16. The Git Project. "config.txt". Retrieved 2024-01-10.
17. The Git Project. "config.txt". Retrieved 2024-01-10.
18. The Git Project. "config.txt". Retrieved 2024-01-10.
19. Cloanto Implementation
20. The Git Project. "config.txt". Retrieved 2024-01-10.
21. The Git Project. "config.txt". Retrieved 2024-01-10.
22. It is a common practice among authors of INI files to "comment out" unwanted entries in order to disable them, instead of removing them completely. See the key a in the following example:

    [section]
    #a=a
    b=b

23. The standard syntax for line continuation refers here to the sequence of a backslash followed by line break, as implemented by iniparser, libconfini and java.util.Properties
24. Fredrik Lundh. "Python Standard Library". 2001. Section "The ConfigParser Module". p. 143
25. "ConfigParser - Configuration file parser".
26. Following the syntax of the language it is designed to work with (Python), to span a node over multiple lines ConfigParser requires a deeper indentation in the lines that follow, instead of the more common backslash + line break (see: configparser — Configuration file parser)
27. Python Documentation by Version
28. GLib Key–value file parser
29. Withnall, Philip (11 Feb 2021). "glib 2.66.7". GNOME ftp-release (Mailing list). Retrieved 12 February 2021.
30. Releases · GNOME/glib
31. inifile documentation
32. Releases · inifile
33. inih README
34. Using indentation, explicitly following ConfigParser's approach (see the project's documentation for more information)
35. Releases · benhoyt/inih
36. iniparser documentation
37. Releases · ndevilla/iniparser
38. Properties (Java Platform SE 8)
39. "OpenJDK: GPLv2 + Classpath Exception". Openjdk.java.net. 1989-04-01. Retrieved 2016-02-09.
40. "BCL For Java SE". Oracle.com. 2013-04-02. Retrieved 2016-02-09.
41. "JDK Releases". Oracle Corporation. Retrieved 2022-12-09.
42. "JDK Releases". Oracle Corporation. Retrieved 2024-01-17.
43. libconfini documentation
44. Releases · madmurphy/libconfini
45. PHP. "parse_ini_file() — Parse a configuration file". Official PHP documentation. Retrieved 2022-07-19.
46. PHP License v3.01[1]
47. "Version 8.3.6". 11 April 2024. Retrieved 13 April 2024.
48. PyINI
49. Tags · whoatemybutter / PyINI
50. python-ini
51. RudeConfig documentation
52. Releases · RudeConfig
53. "April 23, 2024—KB5036980 (OS Builds 22621.3527 and 22631.3527) Preview". Microsoft Support. Microsoft.
54. "Wine 9.0 Released". 16 January 2024. Retrieved 16 January 2024.
55. "configparser on crates.io". crates.io. 2022-12-12. from the original on 2022-12-12. Retrieved 2022-12-12.
56. java-ini-parser github page
57. Initialization Files and the Registry, Windows NT Workstation Resource Kit, Microsoft TechNet
58. Administering the NT Registry, Managing the Windows NT Registry, Paul Robichaux, O'Reilly Media
59. The System Registry
60. Was The Windows Registry a Good Idea? – Coding Horror
61. "Comment on ".INI compatibility is a worthy goal" issue on GitHub". GitHub.
62. libconfini/README

• Infobox - http://filext.com/file-extension/INI
• Infobox - https://wikiext.com/ini

External links

• libconfini's Library Function Manual: The particular syntax allowed by libconfini.
• Cloanto Implementation of INI File Format: The particular syntax allowed by a parser implemented by Cloanto.
• A very simple data file metaformat: INI parser tutorial in Apache Groovy.
• Microsoft's GetPrivateProfileString() and WritePrivateProfileStringA() functions