toml-rs

0.3.12 verified Fri May 01 auth: no python

A high-performance TOML parser for Python written in Rust, supporting TOML 1.0 and 1.1. Current version is 0.3.12, released regularly with wheel builds for many platforms including wasm. Requires Python >=3.10.

pip install toml-rs

Common errors

error ModuleNotFoundError: No module named 'toml' ↓

cause Trying to import 'toml' instead of 'toml_rs'.

fix

Use 'import toml_rs' (the module name is toml_rs, not toml).

error toml_rs._lib.TOMLDecodeError: TOML parse error at line 1, column 9 ... carriage return must be followed by newline, expected newline ↓

cause Input contains a bare carriage return character (\r) not followed by newline (\n).

fix

Replace '\r' with '\r\n' or '\n' before parsing.

error TypeError: loads() got an unexpected keyword argument 'toml_version' ↓

cause Using an older version (<0.2.0?) that doesn't support toml_version.

fix

Upgrade to latest: pip install --upgrade toml-rs

Warnings

gotcha The module name is 'toml_rs' (underscore), not 'toml'. Do not import toml (standard library) or toml-rs (hyphen). ↓

fix Use 'import toml_rs'.

deprecated The toml_version parameter in loads() and load() defaults to '1.0.0' but may be removed in future; specify explicitly if you rely on 1.0 behavior. ↓

fix Pass toml_version='1.0.0' or '1.1.0' explicitly.

gotcha TOML strings with carriage return ('\r') not followed by newline ('\n') raise TOMLDecodeError. This is stricter than some parsers. ↓

fix Normalize input to use '\n' line endings.

gotcha load_with_metadata() returns an object with .data and .meta attributes; it does not return a tuple. ↓

fix Access via result.data and result.meta.

Imports

loads
wrong
```
import toml; toml.loads(...)
```
correct
```
from toml_rs import loads
```
toml-rs is not the standard library toml; it's a separate package with module name toml_rs.
dumps
```
from toml_rs import dumps
```
No common wrong import known.
load
```
from toml_rs import load
```
Load from file.
load_with_metadata
```
from toml_rs import load_with_metadata
```
Returns parsed TOML with metadata.

Quickstart

Basic parsing with loads() and load_with_metadata().

import toml_rs

toml_string = """
title = "Example"
[owner]
name = "Alice"
"""

parsed = toml_rs.loads(toml_string)
print(parsed["title"])  # Example
print(parsed["owner"]["name"])  # Alice

# With metadata
toml_string = "x = 1"
result = toml_rs.load_with_metadata(toml_string, toml_version="1.0.0")
print(result.data)  # {'x': 1}
print(result.meta)  # metadata object