An INI file is a small, forgiving text file, until a misplaced character makes the program ignore the whole thing, reset your settings or refuse to start. A short, careful routine avoids almost all of those outcomes.
1. Make a backup first
Copy the file before you touch it, for example settings.ini.bak in the same folder. If something goes wrong, restoring takes seconds. For files in protected locations, copy it somewhere editable, edit the copy and then replace the original.
2. Close the program that uses it
Many programs rewrite their INI files when they exit. If you edit the file while the program is running, it may overwrite your changes on exit, or never re-read them. Close the program, edit, save, then start it again. Some programs have a reload command, so check the documentation.
3. Use a plain-text editor
Edit with Notepad, a code editor, or Docento's Text & Markdown Editor, which opens .ini files in your browser without uploading them. Avoid word processors, which can add formatting, replace straight quotes with smart quotes, or save in a different file format. Make sure the file keeps the .ini extension and is saved as plain text. On Windows, check that Notepad does not append .txt.
4. Preserve the encoding and line endings
If the original is not UTF-8, saving as UTF-8 can change how non-ASCII characters appear, and a byte order mark can confuse older parsers. Likewise, some programs on Windows expect CRLF line endings. Editors that show or let you choose the encoding and line ending make this easy to check. See text file encodings and LF vs CRLF.
5. Change one thing at a time
Edit a single setting, save, and test. If something breaks you know exactly which edit was responsible. Bulk changes with find-and-replace are tempting and risky, since a replace can touch other sections that share a key name.
6. Respect the structure
- Keep each setting inside its section. Do not add a key above the first
[section]unless the program does. - Keep the
key=valueform. Avoid spaces in key names. - Do not delete the square brackets from a section header.
- Do not leave duplicate keys behind, for instance when you copy a line to modify it. The program may read the last one, not the one you edited.
- Put comments on their own line rather than after a value. Inline comments are not supported everywhere.
7. Use the exact spelling the program expects
Key names and boolean values must match what the program documents. Fullscreen=true may work where Fullscreen=yes is ignored, and an invalid value often falls back to the default with no error. When a change has no effect, check spelling first.
8. Check the syntax before saving over the original
A quick structural check catches the typos that matter. In the Docento editor, a status bar says "Valid INI" or names the first line that is not a comment, a section header or a key=value pair, and clicking it jumps there. This does not know your program's specific keys, only the general structure.
9. Test, then keep the backup for a while
Run the program and confirm the change took effect. Keep the backup until you are sure everything works, including after a restart.
If it goes wrong
- Restore the backup.
- If the program recreated a default file, compare it with your backup to see which settings changed.
- Look at the program's log for a message about the line it could not parse. Our guide to reading log files helps.
Related reading
For what the format allows, see INI file syntax. If the program supports it, a format with types and clearer errors, such as TOML, may be easier to maintain.
Takeaway
Back up, close the program, use a plain-text editor, keep the encoding, change one thing at a time, avoid duplicate keys and check the syntax before you save. Then test and keep the backup until you are sure.
