Configuration files are plain text files that consist of a number of sections, each containing zero or more options:
Empty lines and lines that start with a ‘
#’ in the first column are ignored (except in multi-line-values, see below).
A section starts with a section header. The section header must be the first line in the configuration file, except for empty lines or comments.
The section header starts with a left bracket ‘
[’ in the first column. Everything between the opening bracket and the first right bracket ‘
]’ in the line is the section name. Any text between that right bracket and the end of the line is ignored. The following are valid section headers:
Section names are case-insensitive and case-preserving. This means that, for example, you cannot have two different sections named
[section]; these are both treated as the same section. This becomes important when a section is reopened (see below).
[DEFAULT] section is special: it can be used to define default values for options and is also used for value expansion (see below).
Default values are used when an option is expected to be in a given section but is not defined there. In that case, any option with the same name defined in the
[DEFAULT] section is used instead. For example, given the following configuration file:
the value of “
e” in section
[rational-approximation] will be a quite satisfactory “
2.7182818284590…”, but the value from the
["educational"] section will be a sad “
2.849653908…” which one might as well round up to the definition of “
π” in that section. (That's all assuming that the config parser implemented the function “√
A section is implicitly closed when another section header is encountered. However, the section may be reopened by repeating its section header, and new options can be defined or existing options can be redefined. In the following example,
[section] ends up containing a single option called “
name” whose value is “
An option is a mapping between a name and a value. Options cannot appear outside of a section. Options in different sections are considered separate even if they have the same name.
There are two valid ways to define an option:
The option name must start in the first column of the line and stops at the separator (‘
=’ or ‘
:’). This means that:
- the name cannot start with ‘
[’ or ‘
#’, those characters start a section header or a comment;
- the name may not contain the separators ‘
=’ or ‘
Spaces around the separator are optional and are ignored.
Option names, like section names, are case-insensitive and case preserving; and like section names, option names may contain spaces. But the warnings against relying on case-insensitivity and the use of spaces apply to option names as well.
The options's value is all the text from the separator character until the end of the line. Leading and trailing spaces around the option value are removed, but spaces within the value are preserved.
An option's value may be broken into several lines. Continuation lines must start with at least one space. Trailing spaces in the previous line, the newline character and the leading spaces in the continuation line are removed and replaced with a single space. In the example at the top of this page, the value of the option “
name.2” is “
multi-line value”, note the single space where the value was continued in the next line.
Comments and empty lines may not appear in multi-line values.
At the syntactic level, option values are strings of characters. But certain settings in the configuration files treat them as either logical (Boolean) values or lists.
Any of the following strings are recognised as truth values (case does not matter):
|“True” value||“False” value|
When a value is a list, the list elements are separated by commas ‘
,’. Spaces around each element are trimmed and successive commas are merged. That means you can't have a list element that is an empty string. The list in the following example contains three elements, “
two” and “
Obviously, list elements cannot contain commas.
Note: Some options with list-like values use a different separator (q.v.,
[auto-props]). Always refer to the specific documentation before you modify any settings.
Option values may be expanded within another value by enclosing the option's name in parentheses, preceded by a percent sign ‘
%’ and followed by an ‘
The value of the option “
name.2” is expanded to the value of “
name.1”. Value expansion follows these rules:
- Expansion is performed recursively: e.g., “
name.3” may refer to “
name.2” which refers to “
name.1”, and all the references will be followed.
The referenced option name is first searched for in the same section, and if it is not found there, then in the special
[DEFAULT]section. There is no way to refer to options that are defined in a different section.
If the referenced option name is not found, the whole “
%(name)s” placeholder is left unchanged in the value.
The following is a formal definition of the configuration file syntax, in BNF: