The short answer
- TOML is a text configuration format that maps keys and values unambiguously to a hash table, with case-sensitive names and mandatory valid UTF-8 encoding.
- Open a .toml file in a text editor. On Windows, use the editor's Open command; on Mac, use plain-text mode; on a phone, choose an app that can open UTF-8 text. Preserve UTF-8 when saving. Reading the text does not validate its syntax. Python can parse it with tomllib.load() or tomllib.loads(); invalid documents raise TOMLDecodeError.
- The IANA registration states that TOML contains no executable content. Parsing an untrusted file still carries resource risks: malicious input can consume substantial CPU and memory. Limit the size of data you parse; successful parsing does not establish that its contents are trustworthy.
TOML files: open, edit and convert configuration text
TOML stands for Tom's Obvious, Minimal Language. It uses key = value assignments and supports strings, integers, floats, booleans, dates and times, arrays, tables and arrays of tables. Comments begin with #. Its registered media type is application/toml, its extension is .toml, and it has no fixed magic bytes.
Python tomllib reads TOML into dictionaries but cannot write TOML. For editing existing files while preserving style, the Python documentation recommends TOML Kit. Conversion through a dictionary alone does not guarantee preservation of comments or formatting. Floating-point conversion can also round values; parse_float can select decimal.Decimal.
How to open it
Open a .toml file in a text editor. On Windows, use the editor's Open command; on Mac, use plain-text mode; on a phone, choose an app that can open UTF-8 text. Preserve UTF-8 when saving. Reading the text does not validate its syntax. Python can parse it with tomllib.load() or tomllib.loads(); invalid documents raise TOMLDecodeError.
Open a .toml file in a text editor. On Windows, use the editor's Open command; on Mac, use plain-text mode; on a phone, choose an app that can open UTF-8 text. Preserve UTF-8 when saving. Reading the text does not validate its syntax. Python can parse it with tomllib.load() or tomllib.loads(); invalid documents raise TOMLDecodeError.
Python tomllib reads TOML into dictionaries but cannot write TOML. For editing existing files while preserving style, the Python documentation recommends TOML Kit. Conversion through a dictionary alone does not guarantee preservation of comments or formatting. Floating-point conversion can also round values; parse_float can select decimal.Decimal.
File safety
The IANA registration states that TOML contains no executable content. Parsing an untrusted file still carries resource risks: malicious input can consume substantial CPU and memory. Limit the size of data you parse; successful parsing does not establish that its contents are trustworthy.
An unknown sender, a name ending in two extensions, or contents that do not match the extension — check before you open it.
Converting it
Python tomllib reads TOML into dictionaries but cannot write TOML. For editing existing files while preserving style, the Python documentation recommends TOML Kit. Conversion through a dictionary alone does not guarantee preservation of comments or formatting. Floating-point conversion can also round values; parse_float can select decimal.Decimal.
Convert a copy, never the original, then compare quality, metadata, and layout against what you started with.
Common questions
What is a TOML file used for?
A TOML file stores configuration as text, using key = value assignments that map unambiguously to a hash table. Names are case-sensitive, and the file must be valid UTF-8.
How do I open a TOML file on Windows?
Start a text editor and use Open to select the .toml file. If its file filter hides TOML files, choose all files. Preserve UTF-8 encoding when saving edits.
How do I edit a TOML file on Mac?
Open it in a text editor using plain-text mode. Keep the key = value syntax and save as UTF-8 text with the .toml extension.
How do I open a TOML file on a phone?
Use a text-editing app that can open UTF-8 files and select the .toml file. Available file access and editing controls depend on the app; viewing text alone does not validate TOML.
Why does reading a TOML file raise TOMLDecodeError?
Python raises TOMLDecodeError for an invalid TOML document. Check key = value syntax, quotes, table declarations and valid UTF-8 encoding. Also check version support: Python 3.11 introduced tomllib for TOML 1.0.0; Python 3.15 adds TOML 1.1.0 support.
Should I use a text editor or a Python parser for a TOML file?
Use a text editor to inspect or change the file's text. Use Python tomllib to parse its values into a dictionary and detect invalid TOML. tomllib does not write files or preserve an editable text layout.
How can I convert TOML without losing comments and formatting?
Do not assume that parsing TOML into a dictionary preserves its original text style. For changes that need style preservation, the Python documentation recommends TOML Kit, which supports reading and writing. Check comments and formatting after conversion.
What are the risks of parsing an untrusted TOML file?
TOML contains no executable content according to its IANA registration, but malicious input can make a parser consume substantial CPU and memory. Limit input size before parsing; there is no universal safe size stated here.
Can TOML floating-point precision change during parsing?
Yes. TOML recommends at least IEEE 754 binary64 support, and values exceeding 15 significant decimal digits may be rounded. Python tomllib lets you set parse_float=decimal.Decimal when decimal precision matters.
How do I read TOML files with Python?
Use tomllib.load() with a file opened in binary mode, or tomllib.loads() with a string. Both return a dictionary. The standard-library module is available from Python 3.11 and only reads TOML.
Does successful TOML parsing prove the configuration is trustworthy?
No. Successful parsing means the parser accepted the document. It does not verify the source, the accuracy of values or whether the configuration is suitable for its intended use.
Related formats
Sources
TOML v1.1.0 官方规范 · TOML 官方项目
application/toml 媒体类型登记 · IANA
tomllib — Parse TOML files · Python 官方文档
Tom's Obvious, Minimal Language · 美国国会图书馆