What is an INI file?

INI is a plain-text format you can open in any editor. It is used for editing.

The extension is .ini, and the full name is INI Configuration. Both matter less than what the file can hold, which is what the rest of this page is about.

It dates from 1985.

A format that has been readable for that long is a format worth trusting with something you want back in ten years.

It is published in full, so anyone can implement it from the document rather than by inspection, which is why it turns up in so many programs and why files written twenty years ago still open. A published specification is not the same thing as a royalty-free one: where a format wraps a codec, the patent licensing is a separate question the standard does not settle.

It still opens everywhere and is still written by older tools, but nothing new is being built around it. Convert what you mean to keep, and do not choose it for something starting today.

INI has a comment syntax, which is the difference between a file a person maintains and one a program writes. Comments are the first thing lost converting to a format without them, and nothing warns you.

Notepad and Visual Studio Code read it, and so do most programs of the same kind.

If a file will not open, the format is rarely the problem — it is more often that the program predates it. Converting to something older is the reliable way past that, and it is what the rest of this site is for.

No browser reads it.

That is the single most common reason to convert it: not that the format is bad, but that the place you want to show the file cannot read it.

INI is meant to be opened and changed. Keep the file in this format for as long as the work is going on, and export from it whenever a finished copy is needed.

INI came out of early Windows, where it held the settings for the system and for every application. It was never standardised — no document defines it, no committee owns it, and every program that reads one implements its own dialect.

The core is universal: square-bracketed section headers, and key equals value lines beneath them. Everything past that core is a coin toss. Whether a semicolon or a hash starts a comment. Whether a value may be quoted, and what happens to the quotes. Whether keys are case-sensitive. Whether a value can continue onto a second line. Whether sections can nest, which in most dialects they cannot. Two programs reading the same file can legitimately disagree, and both are right.

Write timeout=30 and the file contains the characters 3 and 0. Whether that becomes a number, and whether it means seconds or milliseconds, is decided entirely by the program reading it. The same applies to true, yes, on and 1 — all common ways of writing a boolean, none of them defined by the format, and each library accepting a different subset.

This is the practical difference from JSON, YAML or TOML, all of which have types. It is why INI configuration files are usually accompanied by documentation or comments explaining what the values mean, and why moving a configuration file between two implementations of the same program is more dangerous than it looks.

Windows, still, in places: desktop.ini controlling how a folder is displayed, boot and driver configuration, and a long tail of applications that have never had a reason to change. Games are a particularly rich source — an enormous number of PC games keep their graphics and input settings in an INI, which is why tweaking guides are full of instructions to edit one.

Elsewhere it survives in tooling that predates the modern alternatives: PHP’s php.ini, Git’s configuration, Python’s setup.cfg and packaging tools, systemd unit files, and any number of small utilities. New projects tend to choose TOML or YAML, but nothing in the existing installations is going to be rewritten.

Any text editor. Two rules cover most of the damage people do: copy the file before changing it, and change one thing at a time — a program that will not start because of a bad configuration file rarely tells you which line it objected to.

Then the details that actually cause failures. Save as UTF-8 without a byte order mark, because the invisible bytes at the start of the file break the first section header in many parsers. Do not add spaces around the equals sign unless you know the reader trims them, since some do not and your value becomes a leading space plus the text. And leave quoting alone: if the existing values are unquoted, adding quotes may add two characters to the value rather than delimiting it.

Being obvious. A person who has never seen the file can open it, find the setting called fullscreen, change false to true, and be right. That is a real property and it is why the format outlived everything designed to replace it in the 1990s.

It also fails gracefully in the shallow case: an unknown key is usually ignored rather than fatal, so a configuration file written for a newer version of a program generally still works with an older one. The alternatives are stricter, which is better for correctness and worse for the person editing a game’s settings at midnight.

When the configuration has grown past flat sections of strings. Nested structure, lists, dates, numbers that need to be numbers, or any value where the difference between the string "false" and the boolean false matters — all of these are where INI stops helping and starts hiding bugs.

TOML was designed as the answer to precisely this: it looks like INI, so nobody has to learn a new shape, and it has a specification, real types and defined nesting. YAML is the other common target and is more powerful and considerably easier to get wrong. If a file is about to grow, TOML is the smaller step and the one that keeps the readability that made INI worth using.