INI file

Initialization

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

The INI file format is an informal standard for configuration files of computing platforms and software. INI files are simple text files with a basic structure composed of sections, properties, and values.

In MS-DOS and 16-bit Microsoft Windows platforms up through Windows ME, the INI file served as the primary mechanism to configure operating system and installed applications features, such as device drivers, fonts, startup launchers, and things that needed to be initialized in booting Windows. INI files were also generally used by applications to store their individual settings.

Starting with Windows NT, Microsoft favored the use of the 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, and applications built on the .NET Framework use special XML .config files. The APIs still exist in Windows, however, and developers may still use them.

The name "INI file" comes from the commonly used filename extension .INI, which stands for "initialization". Other common initialization file extensions are .CFG, .conf, and .TXT, especially CONFIG.SYS and 'config.txt' occurrences.

Linux and Unix systems also use a similar file format for system configuration. In addition, platform-agnostic software may use this file format for configuration. It is human-readable and simple to parse, so it is a usable format for configuration files that do not require much greater complexity.

Git configuration files are similar to INI files.

For example, the platform-agnostic PHP uses the INI format for its "php.ini" configuration file in both Windows and Linux systems.

Desktop.ini files determine how a directory is displayed by Windows, such as the icon used by that directory.

Format

Keys (properties)

The basic element contained in an INI file is the key or property. Every key has a name and a value, delimited by an equals sign (=). The name appears to the left of the equals sign. In the Windows implementation the key cannot contain the characters equal sign ( = ) or semicolon ( ; ) as these are reserved characters. The value can contain any character.

name=value

Sections

Keys may (but need not) be grouped into arbitrarily named sections. The section name appears on a line by itself, in square brackets ([ and ]). All keys after the section declaration are associated with that section. There is no explicit "end of section" delimiter; sections end at the next section declaration, or the end of the file. Sections may not be nested.

[section]
a=a
b=b

Case insensitivity

Section and property names are not case sensitive in the Windows implementation.

Comments

Semicolons (;) at the beginning of the line indicate a comment. Comment lines are ignored.

; comment text

Varying features

The INI file format is not well defined. Many programs support features beyond the basics described above. The following is a list of some common features, which may or may not be implemented in any given program.

Comments

Some software supports the use of the number sign (#) as an alternative to the semicolon for indicating comments. Practically speaking, using it to begin a line may effectively change a variable name on that line. For instance, the following line creates a variable named "#var", but not one named "var"; this is sometimes used to create a pseudo-implementation of a comment.

#var=a

More generally, use of the number sign is unpredictable, as in these following lines (note the space after the number sign in the second line). For this reason, the number sign character should not be used to begin comments.

#[section]
# var=a

In some implementations, a comment may begin anywhere on a line, including on the same line after properties or section declarations. In others, including the WinAPI function GetPrivateProfileString, comments must occur on lines by themselves.

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.

Escape characters

Some implementations also offer varying support for an escape character, typically with the backslash (\). Some support "line continuation", where a backslash followed immediately by EOL (end-of-line) causes the line break to be ignored, and the "logical line" to be continued on the next actual line from the INI file. Implementation of various "special characters" with escape sequences is also seen.

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
\x????	Unicode character with hexadecimal code point corresponding to ????

Global properties

Optional "global" properties may also be allowed, that are declared before any section is declared.

Hierarchy

Most commonly, INI files have no hierarchy of sections within sections. Some files appear to have a hierarchical naming convention, however. For section A, subsection B, sub-subsection C, property P and value V, they may accept entries such as [A.B.C] and P=V (Windows' xstart.ini), [A\B\C] and P=V (the IBM Windows driver file devlist.ini), or [A] and B,C,P = V (Microsoft Visual Studio file AEMANAGR.INI).

It is unclear whether these are simply naming conventions that an application happens to use in order to give the appearance of a hierarchy, or whether the file is being read by a module that actually presents this hierarchy to the application programmer.

Name/value delimiter

Some implementations allow a colon (:) as the name/value delimiter (instead of the equals sign).

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.

Whitespace

Interpretation of whitespace varies. Most implementations ignore leading and trailing whitespace around the outside of the property name. Some even ignore whitespace within values (for example, making "host name" and "hostname" equivalent). Some implementations also ignore leading and trailing whitespace around the property value; others consider all characters following the equals sign (including whitespace) to be part of the value.

Order of sections and properties

In most cases the order of properties in a section and the order of sections in a file is irrelevant, but implementations may vary.

Example

Following is an example INI file for an imaginary program. It has two sections: one for the owner of the software, and one for a payroll database connection. Comments note who modified the file last and why an IP address is used instead of a DNS name.

; 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"

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 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
  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	Multi-line support	Value types	Read/Write support	Platform	License	Programming language	Latest release version
ConfigParser	Yes	No	No	Non-standard	Boolean, Number, String	Read + Write	*BSD, GNU/Linux, macOS, Windows	PSFL	C (implementation), Python (usage)	3.8.2
GLib	Yes	Yes	No	No	Boolean, Number, String, Array	Read + Write	*BSD, GNU/Linux, macOS, Windows	LGPL	C	2.66.7 (February 11, 2021 (2021-02-11)) [±]
inifile	Yes	No	No	No	Boolean, Number, String	Read + Write	*BSD, GNU/Linux, macOS, Windows	Apache	Go	1.2.0
inih	Yes	No	No	Yes	Boolean, Number, String	Read	*BSD, GNU/Linux, macOS, Windows	BSD	C	48
iniparser	Yes	No	No	Yes	Boolean, Number, String	Read + Write	*BSD, GNU/Linux, macOS, Windows	MIT	C	4.1
Java (via java.util.Properties)	No	No	No	Yes	String	Read + Write	Platform-agnostic	Dual-license: GPL version 2 with classpath exception, and a proprietary license.	C (implementation), Java (usage)	23.0.1 (October 15, 2024 (2024-10-15)) [±] 21.0.5 LTS (October 15, 2024 (2024-10-15)) [±] 17.0.13 LTS (October 15, 2024 (2024-10-15)) [±] 11.0.25 LTS (October 15, 2024 (2024-10-15)) [±] 8u431 LTS (October 15, 2024 (2024-10-15)) [±]
libconfini	Yes	Yes	Yes	Yes	Boolean, Number, String, Array	Read	*BSD, GNU/Linux, macOS, Windows	GPL	C	1.14.0
PyINI	Yes	No	Yes	Yes	Boolean, Number, String	Read + Write	Platform-agnostic	GPL	Python	1.0
RudeConfig	Yes	No	No	No	Boolean, Number, String	Read + Write	GNU/Linux, Windows	GPL	C++	Discontinued – last version is 5.0.5, from November 2009
Windows API	Yes	No	No	No	Number, String, Struct	Read + Write (non-destructive)	Windows	Proprietary	C	24H2 (10.0.26100.2161) (October 24, 2024 (2024-10-24)) [±]
Wine (implementation of Windows API)	Yes	No	No	No	Number, String, Struct	Read + Write (non-destructive)	Linux, macOS, Windows	LGPL	C	Template:Latest stable software release/Wine (software)
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 Registry. It was introduced with Windows NT and Windows 95 as a way to migrate from storing settings in classic .ini files to the new Windows 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 above, 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 Windows registry over the INI file. 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.

Later XML-based configuration files became a popular choice for encoding configuration in text files. 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 big subset of INI was rejected.

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.

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

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

External links

Syntax informal specifications

• 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.
• TOML: Formalized configuration format inspired by INI, used in Rust and other projects.
• A very simple data file metaformat: INI parser tutorial in Apache Groovy.

Implementations

• GLib's Key-value file parser
• Microsoft's GetPrivateProfileString() and WritePrivateProfileStringA() functions
• libconfini: Yet another INI parser
• C# INI Reader/Writer: INI Reader/Writer written in C#.
• qLibc - General C Library: INI parser written in C.
• inih: Simple .INI file parser in C: INI parser written in C.
• clinicap (CLiki): INI parser/generator written in Common Lisp.
• Bohr: File format: The particular syntax with hierarchical extensions allowed by a parser implementation called Nickel in a project called Bohr.
• INI C++ Toolkit: Optimized INI text file processor for C++.
• Using INI Files in Pascal