What is a TOML File?Config

A TOML file is a configuration file, using the .toml extension, written in Tom's Obvious Minimal Language. It stores a program's settings in a layout built to be read and edited by hand with as little confusion as possible. Created by Tom Preston-Werner in 2013, it pairs a name with a value using an equals sign and groups settings under headings in square brackets, looking much like a tidied-up INI file. Many developer tools use it for their configuration.

TOML stands for Tom's Obvious Minimal Language. It is named after its creator, Tom Preston-Werner, a co-founder of GitHub, who released it in 2013. The word obvious captures the goal, a configuration file you can read and understand at a glance without first studying the format. Minimal captures the other half, keeping the rules few so the format stays simple. The name is a fair summary of what the format sets out to be.

Both are readable configuration formats that allow comments, but they structure data differently. YAML uses indentation to show nesting, which is compact but means a stray space can quietly change the meaning. TOML uses headings in square brackets instead, so structure does not depend on whitespace, which cuts a whole class of mistakes. TOML also fixes each value's kind firmly, while YAML sometimes guesses, so many people find TOML more predictable for hand-written settings.

JSON is built for data passed between programs, while TOML is built for settings a person writes. The clearest practical differences are that TOML allows comments and JSON does not, and that TOML avoids JSON's heavy brackets and quoting, so it is far easier to edit by hand. JSON remains the better choice when software is generating and reading the data, but for configuration files that people maintain, TOML is the friendlier of the two.

Many developer tools do. Rust's Cargo uses a Cargo.toml to describe a project and its dependencies, and modern Python packaging uses pyproject.toml to say how a project is built. The Hugo website builder keeps its site configuration in TOML, and a long list of linters, formatters and other tools store their options in a .toml. Its plain, predictable layout is a large part of why so many command-line and developer tools have adopted it.

Yes. Because a TOML file maps cleanly onto a plain data structure, it turns into JSON without losing information, and Univik's File Converter does this in the browser. The same works in reverse for most files, though a few shapes that JSON or YAML allow do not fit TOML's rules, so a conversion back into TOML may flag those for you to adjust. Converting is useful when a tool expects one format but your file is in another.

They look similar and are often compared, but TOML is the more capable of the two. Both use headings and name-equals-value lines, which is why anyone who has edited an INI file finds TOML familiar. The difference is that INI has no single agreed standard and cannot express nested data or firm value kinds, while TOML has a formal specification, supports nested tables and gives every value a clear type. TOML is, in effect, INI grown up.

Yes, and it is one of the reasons people choose it. A hash mark begins a comment, which can fill a whole line or sit after a value on the same line, and the parser ignores everything from the hash to the end of the line. This lets you explain what a setting does or why a value was chosen, right next to it. The lack of comments in JSON is a common reason developers prefer TOML for configuration.

It is a TOML configuration file at the root of a Python project, and it is the modern standard for describing how that project is built and packaged. It lists things like the project's name, version and dependencies, and which build tool to use, in place of older separate config files. Because Python can read TOML with its built-in tomllib module, tools across the Python ecosystem now look for pyproject.toml, which is why you often see .toml files in Python projects.

Almost always because of a small syntax slip that stops a program parsing it. A missing quote, bracket or equals sign is the usual culprit, and the error message normally points to the line. Writing a value in the wrong form is another common cause, such as putting a number in quotes so it is read as text. Setting the same name twice in one table also fails. Fixing the flagged line and matching each value to the kind you intend usually clears it.

Python's built-in tomllib reads TOML but cannot write it, so for creating or updating a file you use a separate library. The tomli-w package writes a data structure out as TOML, and tomlkit goes further by editing an existing .toml while preserving its comments and layout, which makes it the better choice when you want to change one value without reformatting the whole file. For simply reading settings, tomllib on its own is enough.

TOML has three ways to write text. A basic string uses double quotes and allows escape codes, so it handles things like tabs and Unicode. A literal string uses single quotes and takes every character exactly as written, with no escaping, which suits Windows file paths and regular expressions where backslashes should stay. A multi-line string uses triple quotes and can run across several lines. Choosing the right one lets a value hold exactly the text you mean.

The surest way is to parse it. If a TOML parser reads the file without raising an error, the file is valid, so running it through a tool like Python's tomllib or an online TOML validator confirms the syntax. An editor with TOML support also flags mistakes as you type. Common things a validator catches are a missing quote or bracket, a value written in the wrong form, and the same key set twice in one table.