View source for INI file

{{Short description|Configuration file format}}
{{Infobox file format
| name = INI
| icon = INI file icon.png
| extension = .ini
| mime = text/plain, application/textedit, zz-application/zz-winassoc-ini
| developer = 
| type = Initialization/Configuration File
| url = 
}}

An '''INI file''' is a [[configuration file]] for [[computer software]] that consists of [[plain text]] with a structure and syntax comprising [[attribute–value pair|key–value pairs]] organized in sections.<ref>[https://technet.microsoft.com/en-us/library/cc731332.aspx Microsoft TechNet: Configure an Ini File Item]</ref> The name of these configuration files comes from the [[filename extension]] ''INI'', short for [[initialization (programming)|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''.<ref>[http://www.fileinfo.com/extension/conf .conf initialization files]</ref>

== 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.<ref>[https://www.microsoft.com/resources/documentation/windowsnt/4/workstation/reskit/en-us/26_ini.mspx Microsoft: Windows NT Workstation Resource Kit]</ref>

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.

* {{code|Desktop.ini}} files are still used in Windows to configure properties of directories, e.g. specifying the icon for a folder.<ref>{{cite web |url=https://learn.microsoft.com/en-us/windows/win32/shell/how-to-customize-folders-with-desktop-ini |date=2022-02-08 |author=Microsoft Learn |title=How to Customize Folders with Desktop.ini |access-date=2024-01-10}}</ref><ref>Codrut Neagu, [https://www.digitalcitizen.life/why-are-there-two-desktopini-files-my-desktop-what-do-they-do "Why Are There Two Desktop.ini Files On My Desktop & What Do They Do?"].</ref>
* [[PHP]]'s {{code|php.ini}} file employs the INI format.<ref>
Rasmus Lerdorf, Kevin Tatroe, Peter MacIntyre.
[https://books.google.com/books?id=h-E1lVko-skC "Programming PHP"].
Sections "parse_ini_file", "Extension INI Entries", etc.
</ref><ref>
Christian Wenz.
[https://books.google.com/books?id=2ndKH7roqiYC "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, ... <code>php.ini</code>"
</ref>
* [[Git]]'s {{code|.git/config}} file is written in an INI flavour.<ref>{{cite web|title=git-config CONFIGURATION FILE|url=https://git-scm.com/docs/git-config#_configuration_file}}</ref>
* [[freedesktop.org]] {{code|*.desktop}} entries are written in an INI flavour.<ref>{{cite web |title=Basic format of the file |url=https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s03.html |website=specifications.freedesktop.org}}</ref>
* [[systemd]] {{code|*.service}} unit configuration files are written in INI.<ref>{{cite web |title=systemd.service |url=https://www.freedesktop.org/software/systemd/man/systemd.service.html |website=www.freedesktop.org}}</ref>
* [[Netatalk]]'s {{code|afp.conf}} file is written in an INI-style configuration language.<ref>{{cite web |url=https://netatalk.sourceforge.io/3.1/htmldocs/afp.conf.5.html |access-date=2024-01-10 |title=afp.conf — Netatalk configuration file}}</ref>
* [[Arch Linux#Pacman|Pacman]]'s {{code|pacman.conf}} file is written in INI.<ref>{{cite web |title=pacman.conf(5) |url=https://archlinux.org/pacman/pacman.conf.5.html |website=archlinux.org}}</ref>
* [[Forgejo]]'s <code>app.ini</code> configuration file is written in INI.<ref>{{Cite web |title=Configuration Cheat Sheet |url=https://forgejo.org/docs/v10.0/admin/config-cheat-sheet/ |access-date=2025-03-12 |website=forgejo.org |language=en}}</ref>

== 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.
<syntaxhighlight lang="ini">
; 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"
</syntaxhighlight>

== 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 <em>INI dialects</em>.

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, <em>INI-flavoured</em> 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-expression]]s, 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. [[Implementation|Implemented]] support is highly volatile. Attempts have been made to create parsers able to support as many dialects as possible.<ref name="libconfini-manual">[https://madmurphy.github.io/libconfini/html/libconfini.html libconfini's Library Function Manual]</ref>

=== 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]] (<code>=</code>, ASCII 0x3D) but sometimes also a colon (<code>:</code>, ASCII 0x3A) or whitespace (occasionally used in the GNU world<ref name="libconfini-manual" />). 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. <code>IconFile=Folder.ico</code>).

Key-value pairs may textually look like:

<syntaxhighlight lang="ini">
key=key=v
  name =value
sem=;
semver=v5822.433.2
</syntaxhighlight>

=== 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 <em>global properties</em>.<ref>[http://commons.apache.org/proper/commons-configuration/apidocs/org/apache/commons/configuration2/INIConfiguration.html Apache Documentation for org.apache.commons.configuration2.INIConfiguration], The Apache Software Foundation</ref> When key-value pairs are grouped, the section name appears on a line by itself, enclosed in [[bracket|square brackets]] (<code>[</code>, ASCII 0x5B, and <code>]</code>, 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 <code>&lt;/tag&gt;</code>). 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 <code>.</code>, ASCII 0x2E). One level of nesting is often supported, called ''subsections''.

Exemplary INI document employing nested sections:
<syntaxhighlight lang="ini">
[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.
</syntaxhighlight>

==== Hierarchy (section nesting) ====
Some parsers allow section nesting, using dots as path delimiters:

<syntaxhighlight lang="ini">
[section]
domain = example.com

[section.subsection]
foo = bar
</syntaxhighlight>

In some cases relative nesting is supported too, where a leading dot expresses nesting to the previous section:<ref name="libconfini-manual" />

<syntaxhighlight lang="ini">
[section]
domain = example.com

[.subsection]
foo = bar
</syntaxhighlight>

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

=== Case sensitivity ===
Section and property names in Windows are [[Case sensitivity|case insensitive]].<ref>This includes the Windows implementation. See {{cite web|url=http://msdn.microsoft.com/en-us/library/ms724353.aspx|title=GetPrivateProfileString function|work=Microsoft Developer Network|publisher=Microsoft|access-date=2012-06-02}}</ref> Most Unix-style INI interpretations forbid case folding altogether, although case folding for the section name<ref>{{cite web |url=https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/config.txt?id=a54a84b333adbecf7bc4483c0e36ed5878cac17b#n54 |title=config.txt |author=The Git Project |access-date=2024-01-10}}</ref> or key<ref>{{cite web |url=https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/config.txt?id=a54a84b333adbecf7bc4483c0e36ed5878cac17b#n63 |title=config.txt |author=The Git Project |access-date=2024-01-10}}</ref> is sometimes allowed.

=== Comments ===
A line with contiguous trailing whitespace followed by a [[semicolon]] (<code>;</code>, ASCII 0x3E) indicates a [[comment (computer programming)|comment]]. Some INI dialects furthermore allow use of the [[number sign]] (<code>#</code>, ASCII 0x23) to denote a comment, mirroring Unix [[Bourne shell|shell]] comments. Some INI dialects but not all allow a comment on a key-value pair line or section line (called <em>in-line comment</em>), 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.
<syntaxhighlight lang="ini">
#! /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
</syntaxhighlight>
Under the [[Windows API|WinAPI]]'s <em>GetPrivateProfileString</em>'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 (computing)|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 [[Quotation mark|double quotes]] and/or [[apostrophe]]s. This allows for explicit declaration of whitespace, and/or for quoting of special characters (equals, semicolon, etc.). The standard Windows function [https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-getprivateprofilestringw 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 (<code>\</code>, ASCII 0x5C) as the last character on a line.<ref>{{cite web |url=https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/config.txt?id=a54a84b333adbecf7bc4483c0e36ed5878cac17b#n66 |title=config.txt |access-date=2024-01-10 |author=The Git Project}}</ref> In such <em>line continuation</em>, backslashes followed immediately by EOL (end-of-line) cause the backslash and line break to be dropped, transforming the document's lines into <em>logical lines</em>.

=== Escape characters ===
Some dialects offer varying support for [[escape character|character escaping]], typically with the [[backslash]] character (<code>\</code>, ASCII 0x5C) as a metacharacter and emulating [[C syntax]].<ref>Cloanto Implementation</ref>

It is not wise to blindly interpret escape sequences as some specifications explicitly mute their metacharacter for common escape sequences.<ref>{{cite web |url=https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/config.txt?id=a54a84b333adbecf7bc4483c0e36ed5878cac17b#n47 |title=config.txt |access-date=2024-01-10 |author=The Git Project}}</ref><ref>{{cite web |url=https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/config.txt?id=a54a84b333adbecf7bc4483c0e36ed5878cac17b#n79 |title=config.txt |access-date=2024-01-10 |author=The Git Project}}</ref>

{| class="wikitable" 
|+ Common escape sequences
! Sequence
! Meaning
|-
| <code>\\</code>
| \ (a single [[backslash]], escaping the escape character)
|-
| <code>\'</code>
| [[Apostrophe]]
|-
| <code>\"</code>
| [[Double quotes]]
|-
| <code>\0</code>
| [[Null character]]
|-
| <code>\a</code>
| [[Bell character|Bell/Alert/Audible]]
|-
| <code>\b</code>
| [[Backspace]], [[Bell character]] for some applications
|-
| <code>\t</code>
| [[Tab key|Tab character]]
|-
| <code>\r</code>
| [[Carriage return]]
|-
| <code>\n</code>
| [[Line feed]]
|-
| <code>\;</code>
| [[Semicolon]]
|-
| <code>\#</code>
| [[Number sign]]
|-
| <code>\=</code>
| [[Equals sign]]
|-
| <code>\:</code>
| [[Colon (punctuation)|Colon]]
|-
| <code>\x''hhhh''</code>
| [[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 {{code|.ini}} files. For example, the [http://msdn.microsoft.com/en-us/library/ms724353(VS.85).aspx GetPrivateProfileString] function retrieves a string from the specified section in an initialization file. (The "private" profile is contrasted with {{code|GetProfileString}}, which fetches from [[WIN.INI]].)

The following sample [[C (programming language)|C]] program demonstrates reading property values from the above sample INI file (let the name of configuration file be <code>dbsettings.ini</code>):
<syntaxhighlight lang="c" line>
#include <windows.h>

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

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

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 [https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html GLib], [https://gitlab.com/iniparser/iniparser iniparser] and [https://github.com/madmurphy/libconfini libconfini].

=== Comparison of INI parsers ===

<!-- In each table, link one instance of terms, in body and notes, remove other WP:REPEATLINK(s). -->
{{sort-under}}
{| class="wikitable sortable sort-under" style="font-size:smaller; text-align: center; width: auto"
|-
! Name
! Sections support
! Section nesting support
! Disabled entry recognition<ref name="disabled-entry">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 <code>a</code> in the following example:{{Pre|[section]<br />#a{{=}}a<br />b{{=}}b}}</ref>
! Multi-line support<ref name="multiline-entry">The standard syntax for line continuation refers here to the sequence of a [[backslash]] followed by [[Newline|line break]], as implemented by [[iniparser]], [[libconfini]] and <code>java.util.Properties</code></ref>
! Value types
! Read/Write support
! [[computing platform|Platform]]
! [[Software license|License]]
! [[Programming language]]
! Latest release version
|-
| Python ConfigParser<ref>
Fredrik Lundh.
[https://books.google.com/books?id=PIlQzfnpn5cC "Python Standard Library"].
2001.
Section "The ConfigParser Module".
p. 143
</ref><ref>
[https://docs.python.org/3/library/configparser.html "ConfigParser - Configuration file parser"].
</ref>
| {{yes}}
| {{yes}}
| {{no}}
| {{some|Non-standard}}<ref>Following the syntax of the language it is designed to work with ([[Python (programming language)|Python]]), to span a node over multiple lines ConfigParser requires a deeper [[Indentation style|indentation]] in the lines that follow, instead of the more common [[backslash]] + [[Newline|line break]] (see: [https://docs.python.org/3/library/configparser.html#supported-ini-file-structure configparser — Configuration file parser])</ref>
| [[Boolean data type|Boolean]], [[Data type#Numeric types|Number]], [[Data type#String and text types|String]]
| Read + Write
| [[Berkeley Software Distribution|*BSD]], [[Linux]], [[macOS]], [[Microsoft Windows|Windows]]
| {{open source|[[Python Software Foundation License|PSFL]]}}
| [[C (programming language)|C]] (implementation), [[Python (programming language)|Python]] (usage)
| 3.9.7<ref>[https://www.python.org/doc/versions/ Python Documentation by Version]</ref>
|-
| [[GLib]]<ref>[https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html GLib Key–value file parser]</ref>
| {{yes}}
| {{yes}}
| {{no}}
| {{no}}
| [[Boolean data type|Boolean]], [[Data type#Numeric types|Number]], [[Data type#String and text types|String]], [[Array data type|Array]]
| Read + Write
| [[Berkeley Software Distribution|*BSD]], [[Linux]], [[macOS]], [[Microsoft Windows|Windows]]
| {{open source|[[GNU Lesser General Public License|LGPL]]}}
| [[C (programming language)|C]]
| {{Latest_stable_software_release/GLib}}<ref>[https://github.com/GNOME/glib/releases Releases · GNOME/glib]</ref>
|-
| [[inifile]]<ref>[https://github.com/graniticio/inifile inifile documentation]</ref>
| {{yes}}
| {{no}}
| {{no}}
| {{no}}
| [[Boolean data type|Boolean]], [[Data type#Numeric types|Number]], [[Data type#String and text types|String]]
| Read + Write
| [[Berkeley Software Distribution|*BSD]], [[Linux]], [[macOS]], [[Microsoft Windows|Windows]]
| {{open source|[[Apache License|Apache]]}}
| [[Go (programming language)|Go]]
| 1.2.0<ref>[https://github.com/graniticio/inifile/releases Releases · inifile]</ref>
|-
| [[inih]]<ref>[https://github.com/benhoyt/inih/blob/master/README.md inih README]</ref>
| {{yes}}
| {{no}}
| {{no}}
| {{some|Non-standard}}<ref>Using indentation, explicitly following ConfigParser's approach (see the project's documentation for more information)</ref>
| [[Boolean data type|Boolean]], [[Data type#Numeric types|Number]], [[Data type#String and text types|String]]
| Read
| [[Berkeley Software Distribution|*BSD]], [[Linux]], [[macOS]], [[Microsoft Windows|Windows]]
| {{open source|[[BSD licenses|BSD]]}}
| [[C (programming language)|C]]
| 60<ref>[https://github.com/benhoyt/inih/releases Releases · benhoyt/inih]</ref>
|-
| [[iniparser]]<ref>[https://iniparser.gitlab.io/iniparser/ iniparser documentation]</ref>
| {{yes}}
| {{no}}
| {{no}}
| {{yes}}
| [[Boolean data type|Boolean]], [[Data type#Numeric types|Number]], [[Data type#String and text types|String]]
| Read + Write
| [[Berkeley Software Distribution|*BSD]], [[Linux]], [[macOS]], [[Microsoft Windows|Windows]]
| {{open source|[[MIT License|MIT]]}}
| [[C (programming language)|C]]
| 4.2.4<ref>[https://gitlab.com/iniparser/iniparser/-/releases Releases · iniparser/iniparser]</ref>
|-
| [[Java (programming language)|Java]] (via <code>java.util.Properties</code>)<ref>[https://docs.oracle.com/javase/8/docs/api/index.html?java/util/Properties.html Properties (Java Platform SE 8)]</ref>
| {{no}}
| {{no}}
| {{no}}
| {{yes}}
| [[Data type#String and text types|String]]
| Read + Write
| Platform-agnostic
| {{open source|Dual-license: [[GNU General Public License|GPL]] version 2 with classpath exception,<ref>{{cite web|url=https://openjdk.java.net/legal/gplv2+ce.html |title=OpenJDK: GPLv2 + Classpath Exception |publisher=Openjdk.java.net |date=1989-04-01 |access-date=2016-02-09}}</ref> and a [[proprietary software|proprietary]] license.<ref>{{cite web|url=https://www.oracle.com/technetwork/java/javase/terms/license/index.html |title=BCL For Java SE |publisher=Oracle.com |date=2013-04-02 |access-date=2016-02-09}}</ref>}}
| [[C (programming language)|C]] (implementation), [[Java (programming language)|Java]] (usage)
| {{Latest_stable_software_release/Java_(software_platform)}}
|-
| [[libconfini]]<ref>[https://madmurphy.github.io/libconfini/ libconfini documentation]</ref>
| {{yes}}
| {{yes}}
| {{yes}}
| {{yes}}
| [[Boolean data type|Boolean]], [[Data type#Numeric types|Number]], [[Data type#String and text types|String]], [[Array data type|Array]]
| Read
| [[Berkeley Software Distribution|*BSD]], [[Linux]], [[macOS]], [[Microsoft Windows|Windows]]
| {{open source|[[GNU General Public License|GPL]]}}
| [[C (programming language)|C]]
| 1.16.2<ref>[https://github.com/madmurphy/libconfini/releases Releases · madmurphy/libconfini]</ref>
|-
| [[PHP]] (via <code>parse_ini_file()</code>)<ref>{{cite web
  | url = https://www.php.net/manual/en/function.parse-ini-file.php
  | title = <code>parse_ini_file()</code> — Parse a configuration file
  | author = PHP
  | author-link = PHP
  | website = Official PHP documentation
  | access-date = 2022-07-19
}}</ref>
| {{yes}}
| {{yes}}
| {{yes}}
| {{no}}
| [[Boolean data type|Boolean]], [[Data type#Numeric types|Number]], [[Data type#String and text types|String]], [[Null pointer|Null]]
| Read
| [[Linux]], [[macOS]], [[Windows]]
| {{open source|[[PHP License]] v3.01<ref>[https://www.php.net/license/3_01.txt PHP License v3.01]</ref>}}
| [[C (programming language)|C]] (implementation), [[PHP]] (usage)
| {{wikidata|property|reference|edit|Q59|P548=Q2804309|P348}} ({{start date and age|{{wikidata|qualifier|single|Q59|P548=Q2804309|P348|P577}}}})
|-
| [https://gitlab.com/whoatemybutter/pyini PyINI]<ref>[https://gitlab.com/whoatemybutter/pyini/ PyINI]</ref>
| {{yes}}
| {{yes}} (up to two sections)
| {{yes}}
| {{yes}}
| [[Boolean data type|Boolean]], [[Data type#Numeric types|Number]], [[Data type#String and text types|String]], [[Array (data type)|Array]]
| Read + Write
| Platform-agnostic
| {{open source|[[GNU General Public License|GPLv3]]}}
| [[Python (programming language)|Python]]
| 2.1<ref>[https://gitlab.com/whoatemybutte7/pyini/-/tags Tags · whoatemybutter / PyINI]</ref>
|-
| [https://github.com/ldthomas/python-ini python-ini]<ref>[https://github.com/ldthomas/python-ini python-ini]</ref>
| {{yes}}
| {{no}}
| {{no}}
| {{yes}}
| [[Boolean data type|Boolean]], [[Data type#Numeric types|Number]], [[Data type#String and text types|String]], [[Null pointer|Null]]
| Read + Write
| Platform-agnostic
| {{open source|[[BSD licenses|BSD]]}}
| [[Python (programming language)|Python]]
| 1.1.0
|-
| [[RudeConfig]]<ref>[http://rudeserver.com/config/index.html RudeConfig documentation]</ref>
| {{yes}}
| {{no}}
| {{no}}
| {{no}}
| [[Boolean data type|Boolean]], [[Data type#Numeric types|Number]], [[Data type#String and text types|String]]
| Read + Write
| [[Linux]], [[Microsoft Windows|Windows]]
| {{open source|[[GNU General Public License|GPL]]}}
| [[C++]]
| {{dropped|Discontinued – last version is 5.0.5, from November 2009<ref>[http://rudeserver.com/config/download.html Releases · RudeConfig]</ref>}}
|-
| [[Windows API]]
| {{yes}}
| {{no}}
| {{no}}
| {{no}}
| [[Data type#Numeric types|Number]], [[Data type#String and text types|String]], [[Record (computer science)|Struct]]
| Read + Write (non-destructive)
| [[Microsoft Windows|Windows]]
| {{proprietary}}
| [[C (programming language)|C]]
| {{Latest_stable_software_release/Microsoft_Windows}}
|-
| [[Wine (software)|Wine]] (implementation of [[Windows API]])
| {{yes}}
| {{no}}
| {{no}}
| {{no}}
| [[Data type#Numeric types|Number]], [[Data type#String and text types|String]], [[Record (computer science)|Struct]]
| Read + Write (non-destructive)
| [[Linux]], [[macOS]], [[Windows]]
| {{open source|[[GNU Lesser General Public License|LGPL]]}}
| [[C (programming language)|C]]
| {{wikidata|property|reference|edit|Q188558|P548=Q2804309|P348}} {{start date and age|{{wikidata|qualifier|Q188558|P548=Q2804309|P348|P577}}}}
|-
| Rust configparser<ref name=":0">{{Cite web |date=2022-12-12 |title=configparser on crates.io |url=https://crates.io/crates/configparser |url-status=live |archive-url=https://web.archive.org/web/20221212151521/https://crates.io/crates/configparser |archive-date=2022-12-12 |access-date=2022-12-12 |website=crates.io}}</ref>
| {{yes}}
| {{no}}
| {{no}}
| {{no}}
|[[Boolean data type|Boolean]], [[Data type#Numeric types|Number]], [[Data type#String and text types|String]]
|Read + Write
|[[Berkeley Software Distribution|*BSD]], [[Linux]], [[macOS]], [[Microsoft Windows|Windows]]
| {{open source|[[MIT License|MIT]] or [[GNU Lesser General Public License|LGPL]] v3.0+}}
|[[Rust (programming language)|Rust]]
|3.0.2<ref name=":0" /> 11 September 2022; 3 months ago
|-
| [[java-ini-parser]]<ref>[https://github.com/vincentrussell/java-ini-parser java-ini-parser github page]</ref>
| {{yes}}
| {{no}}
| {{yes}}
| {{yes}}
|[[Boolean data type|Boolean]], [[Data type#Numeric types|Number]], [[Data type#String and text types|String]]
|Read + Write
|Platform-agnostic
| {{open source|[[Apache License|Apache]]}}
|[[Java (programming language)|Java]]
|1.4<ref name=":0" /> 29 December 2022; 3 days ago
|- class="sortbottom"
! Name
! Sections support
! Section nesting support
! Disabled entry recognition
! Multi-line support
! Value types
! Read/Write support
! [[computing platform|Platform]]
! [[Software license|License]]
! [[Programming language]]
! Latest release version
|}

== File mapping ==
Initialization file mapping creates a mapping between an INI file and the [[Windows registry]].<ref>[https://technet.microsoft.com/en-ie/library/cc722567(en-us).aspx Initialization Files and the Registry], ''Windows NT Workstation Resource Kit'', [[Microsoft TechNet]]</ref><ref>[http://oreilly.com/catalog/manwinreg/chapter/ch08.html Administering the NT Registry], ''Managing the Windows NT Registry'', Paul Robichaux, O'Reilly Media</ref> It was introduced with Windows NT and Windows 95 as a way to migrate from storing settings in classic {{code|.ini}} files to the new registry. File mapping traps the Profile API calls and, using settings from the {{em|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, {{code|dbsettings.ini}}. The returned value should be the string "John Doe":

<syntaxhighlight lang="csharp">
GetPrivateProfileString("owner", "name", ... , "c:\\programs\\oldprogram\\dbsettings.ini");
</syntaxhighlight>

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:

:<code>HKEY_LOCAL_MACHINE\Software\Microsoft\Windows&nbsp;NT\<wbr/>CurrentVersion\IniFileMapping</code>

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 {{code|{{em|(Default)}}}} entry name, INI mapping uses that instead. Thus each section name does not need its own entry.

{| class="wikitable" style="font-family:monospace; text-align:center;"
|+ HKEY_LOCAL_MACHINE\Software\...\IniFileMapping\dbsettings.ini
|-
! scope="row" | {{em|(Default)}}  
|  @USR:Software\oldprogs\inisettings\all
|-
! scope="row" | {{em|database}}   
|  USR:Software\oldprogs\inisettings\db
|}

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

{| class="wikitable" style="font-family:monospace; text-align:center;"
|+ HKEY_CURRENT_USER\Software\oldprogs\inisettings\all
|-
! scope="row" | {{em|name}}   
| John Doe
|-
! scope="row" | {{em|organization}} 
| Acme Products
|}

where the "{{em|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 {{code|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 "{{em|database}}" Registry entry does not have the @ prefix on the value; thus, for the <code>[database]</code> section ''only'', settings in the Registry are taken first followed by settings in the {{code|dbsettings.ini}} file on disk.

== Alternatives ==
Starting with [[Windows 95]], Microsoft began strongly promoting the use of the [[Windows Registry]] over INI files.<ref>[https://msdn.microsoft.com/en-us/library/ms970651.aspx The System Registry]</ref> 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.<ref>[https://blog.codinghorror.com/was-the-windows-registry-a-good-idea/ Was The Windows Registry a Good Idea? – Coding Horror]</ref>

Later [[XML]]-based configuration files became a popular choice for encoding configuration in text files.{{Citation needed|date=January 2014}} XML allows arbitrarily complex levels and nesting, and has standard mechanisms for encoding [[binary file|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.<ref>{{cite web |title=Comment on ".INI compatibility is a worthy goal" issue on GitHub|website=[[GitHub]] |url=https://github.com/toml-lang/toml/issues/411#issuecomment-219203431}}</ref>

The newest INI parsers however allow the same arbitrary level of nesting of [[XML]], [[JSON]], [[TOML]], and [[YAML]], offer equivalent support of [[Data type|typed values]] and [[Unicode]], although keep the "informal status" of INI files by allowing multiple syntaxes for expressing the same thing.<ref>[https://github.com/madmurphy/libconfini/ libconfini/README]</ref>

== See also ==
* [[NTLDR#boot.ini|BOOT.INI]]
* [[MSConfig]]
* [[Sysedit]]
* [[SYSTEM.INI]]
* [[TOML]], a very similar but more formally-specified configuration file format
* [[WIN.INI]]
* [[Amiga]]'s [[Interchange File Format|IFF]] files
* [[.DS_Store]]
* [[.properties]]

== References ==
{{Reflist}}
* Infobox - http://filext.com/file-extension/INI
* Infobox - https://wikiext.com/ini
* More Info - https://wednesdaycake.com/INI

== External links ==
* [https://madmurphy.github.io/libconfini/html/libconfini.html libconfini's Library Function Manual]: The particular syntax allowed by libconfini.
* [https://cloanto.com/specs/ini/ Cloanto Implementation of INI File Format]: The particular syntax allowed by a parser implemented by Cloanto.
* [http://octodecillion.com/blog/very-simple-data-file-format A very simple data file metaformat]: INI parser tutorial in Apache Groovy.
* Microsoft's [https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-getprivateprofilestring GetPrivateProfileString()] and [https://docs.microsoft.com/it-it/windows/win32/api/winbase/nf-winbase-writeprivateprofilestringa WritePrivateProfileStringA()] functions

[[Category:Configuration files]]
[[Category:Computer file formats]]