INI syntax is simple enough that people write it without reading any rules, and then wonder why a setting is ignored. This guide covers the common structure and the points where programs differ. Because there is no formal standard, treat it as a description of typical behaviour, and always confirm in the documentation of the program that reads your file.
Sections
A section header is a name in square brackets on its own line:
[Network]
Keys that follow belong to that section until the next header. Keys that appear before any header belong to a global or default section in some parsers, and cause an error in others. Section names are usually case-insensitive in Windows tools and case-sensitive in many others. Avoid putting other characters on the header line, except possibly a comment in dialects that allow it.
Keys and values
A setting is a name, a separator and a value:
timeout=30
name = Docento
path : /usr/local
- The separator is
=in nearly all dialects, and some accept:too. - Whitespace around the separator is generally ignored.
- Whitespace at the start and end of the value is usually trimmed.
- A key without a separator is an error in strict parsers, and may be treated as a flag with an empty value in lenient ones.
Everything after the first separator is the value, so url=https://example.com/?a=1 is one value, even with = inside it, in most parsers.
Comments
; semicolon comment
# hash comment (not universal)
A comment must usually be on its own line. Inline comments after a value, such as timeout=30 ; seconds, are supported by some parsers and not by others. Where they are not supported, 30 ; seconds becomes the value, and a program that expects a number fails or silently uses a default. If unsure, put comments on separate lines.
Quotes
Whether quotes are part of the value depends on the parser. The Windows profile functions strip matching quotes around a value, while Python's configparser keeps them as part of the value. When a value has leading or trailing spaces that matter, or contains a comment character, check how the program handles quoting.
Multi-line values
Some parsers allow a value to continue on following lines if they are indented:
description = This is a long value
that continues on the next line
Others treat the indented line as an error. Do not rely on it without checking.
Duplicates
- Duplicate keys in a section: the last value wins in some parsers, and a strict parser raises an error in others.
- Duplicate section headers: merged in some, an error in others.
Duplicates are a frequent cause of "my edit does nothing": you changed the first copy and the program reads the last.
Data types
INI has none. true, 42 and 3.14 are all strings. The program decides how to interpret them, and each uses its own list of accepted boolean spellings, such as true/false, yes/no, on/off or 1/0. Use the spelling the program documents.
Encoding and line endings
Older Windows INI files may be in a legacy code page, while newer programs expect UTF-8. A byte order mark at the start of a file can make the first section header unrecognised by some parsers. See text file encodings and LF vs CRLF line endings.
Common mistakes
- A setting placed before any section, when the program requires one
- An inline comment treated as part of the value
- A misspelt key that the program silently ignores
- Duplicate keys with the wrong one winning
- Smart quotes copied from a document
- A missing closing bracket on a section header
Checking structure
Docento's Text & Markdown Editor checks .ini files against the common pattern: each line must be blank, a ; or # comment, a [section] header or a key=value (or key: value) pair, with indented continuation lines allowed. It reports the first line that breaks the pattern, such as a malformed section header. It cannot tell whether a key name is valid for your program.
Takeaway
INI is sections and key=value lines with comments, but details such as inline comments, quotes, duplicates and continuation vary by program. Put comments on their own lines, avoid duplicates and read the program's documentation for its dialect.
