Convert YAML to INI

INI has exactly one level of grouping: a bracketed section and the keys inside it. YAML has as many levels as you care to indent. The conversion resolves that by walking the whole tree, building a dotted path for every leaf value, and then splitting each path once — the part before the first dot becomes the section, the rest becomes the key.

So a YAML mapping named database, containing pool, containing timeout, produces a section named database and a key named pool.timeout. Every value in the document survives; only the shape is gone. A parser on the other side sees flat keys with dots in them and has no way to know which dots were nesting and which were part of a name.

A YAML sequence has no equivalent in INI, so each item becomes a key named after its index. A build script written as a list of three commands comes out as script.0, script.1 and script.2 inside the job section, in the order they were written.

Order is preserved, which is the part that matters, but the convention is ours rather than a standard. Some INI parsers understand numbered keys as a list, most do not, and a few expect a repeated key name instead. Check what the program reading the file does with them before assuming the list survived in any meaningful sense — an ordered sequence that arrives as three unrelated settings has been converted correctly and understood wrongly.

A list at the top level of the document has no key to be numbered under, so it becomes a section named after whatever key held it, with 0, 1 and 2 as its key names. A YAML file whose stages key holds two entries produces a section headed stages with a key named 0 and a key named 1.

A section full of numbers is legal INI and looks wrong to anybody reading it. If the destination program expects a comma-separated list in a single key — which is the usual INI idiom for a sequence — join the list in the YAML before converting, or in the INI afterwards. There is no setting that will do it for you, because the two conventions cannot both be right.

A YAML block scalar — a pipe character followed by an indented block, which is how every CI file holds a shell script — parses into a single string with newlines inside it. Until 2026-08-09 the writer emitted that string exactly as it stood, so the newlines became real line breaks: the first line of the script sat after the equals sign and every line below it stood alone. Reading such a file back discarded those lines, and any of them that looked like a bracketed header opened a section that was never in the YAML, taking the following key with it.

The writer now quotes a multi-line value and writes each break as a backslash and an n, so the script stays on one line, stays one entry, and comes back unchanged through this converter. What has not changed is the destination: INI dialects disagree about escapes, and a parser that treats a backslash as an ordinary character will hand your script back with those two characters in it. If the program reading the file matters more than the round trip, fold the value to one line in the YAML or keep the script in its own file and point the INI at the path.

A YAML key with nothing after it parses to null and is written as the key, an equals sign, and nothing. INI cannot express the difference between an unset key and an empty string, so both come back as an empty string on the other side. If the distinction matters to the program reading the file, it has to be encoded some other way — a sentinel value, or leaving the key out entirely.

Booleans are written as the words true and false. That is what the source said, and it is not what every INI consumer expects: Windows configuration and php.ini use On and Off, and a parser looking for those will treat true as an unrecognised string. Quoting is applied only where a value would not otherwise survive being read back — a line break in it, a space at either end, or quotes around it already — so ordinary values keep their punctuation and their bare appearance. A value containing an equals sign is left alone and still reads back correctly, because INI parsers split at the first one.

A config that is two levels deep, holds scalars, and has no multi-line values converts perfectly and needs no editing. A great many application configs are exactly that shape, which is why the pair exists — a docker-compose environment block or a set of feature flags flattens without losing anything a reader would notice.

A file with lists of mappings does not. A YAML list of server definitions, each with a host and a port, becomes servers.0.host, servers.0.port, servers.1.host and so on inside one section, which is a faithful encoding of the data and an unreadable configuration file. If that is your source, the honest advice is that INI is not a suitable destination and the conversion is producing something you will have to rewrite anyway.

A scalar at the very top level of the YAML — a version, a name, a single flag — has no parent to become a section. Those values are written first, before any bracketed header, which is the standard INI idiom for a global block and is understood by most parsers.

Section blocks follow, in the order their keys appeared in the YAML. That ordering is worth knowing if the file is reviewed by eye rather than by machine, because it means the output reads in roughly the same sequence as the source and a diff between two conversions of the same file stays legible.

Comments are dropped. Both formats support them, the parser discards them while reading, and the writer has nothing to write back. The explanation above a timeout is exactly the sort of line that made the YAML worth reading, and it is not in the INI.

A file containing --- separators fails outright rather than converting partially. That is deliberate: a YAML stream can hold several documents, an INI file describes one set of settings, and picking the first document silently would produce a config that is missing most of itself. Split the file and convert the document you actually need.

The conversion is worth running when the YAML is large, flat and dull. It is not worth running when the source is small — twenty settings are faster to retype than to convert and then repair, and retyping forces you to read each value once, which is a benefit rather than a cost on a config that is about to be trusted by an old program.

It is also the wrong tool when the destination expects a specific INI dialect. Programs that want quoted values, On and Off booleans, comma-separated lists or repeated keys are asking for conventions this writer does not produce. Convert to get the values out of the tree, then reshape to fit the parser you are actually feeding.