Tomli-W: A Minimal TOML Writer

1.2.0 verified Tue May 12 auth: no python install: verified

Tomli-W is a pure Python library designed for writing TOML (Tom's Obvious, Minimal Language) documents. It acts as the write-only counterpart to the `tomli` parser (which is also the basis for the `tomllib` standard library module in Python 3.11+). It is fully compatible with TOML v1.0.0 and focuses on simplicity and correctness in output. The library maintains an active status with periodic updates.

pip install tomli-w

Common errors

error ModuleNotFoundError: No module named 'tomli_w' ↓

cause The `tomli-w` package is not installed in the current Python environment, or the module name `tomli_w` is misspelled.

fix

Install the library using pip: pip install tomli-w

error AttributeError: module 'tomli_w' has no attribute 'load' ↓

cause `tomli-w` is a write-only library designed for creating TOML documents and does not include functions for parsing (reading) TOML files.

fix

Use the tomli library (or tomllib in Python 3.11+) to read TOML files, e.g., import tomli then tomli.load(fp).

error TypeError: Object of type set is not TOML serializable ↓

cause `tomli-w` encountered a Python object type (like a `set` or custom class instance) that cannot be directly represented in the TOML specification.

fix

Ensure all values in the dictionary intended for serialization are standard TOML-compatible types (strings, integers, floats, booleans, lists, dictionaries, datetime objects). Convert unsupported types to a serializable form if necessary.

error AttributeError: 'str' object has no attribute 'write' ↓

cause The `tomli_w.dump()` function expects a file-like object (opened in write mode) as its second argument, not a string representing a file path.

fix

Open the file in write mode using open() and pass the resulting file object to tomli_w.dump(), for example: with open('config.toml', 'wb') as f: tomli_w.dump(data, f).

Warnings

breaking `tomli-w` requires Python 3.9 or newer. Attempts to use it on older Python versions will result in an `ImportError` or `SyntaxError`. ↓

fix Ensure your Python environment is 3.9 or newer. Consider `tomllib` (Python 3.11+) or `tomlkit` for broader compatibility needs if you need a writer for older Python versions.

gotcha `tomli-w` does not preserve comments, original ordering (beyond respecting input dictionary order), or custom whitespace. For style-preserving writing (e.g., maintaining comments, specific indentation), `tomlkit` is a recommended alternative. ↓

fix If style preservation is critical, evaluate `tomlkit`. Otherwise, ensure your workflow does not depend on output TOML mirroring input formatting precisely.

gotcha The library does not automatically validate the generated TOML. If the input data contains non-standard types or structures that could result in invalid TOML (e.g., objects whose `__str__` method produces invalid TOML syntax), `tomli-w` will write it without raising an error. It's recommended to validate the output by parsing it with a TOML reader like `tomli.loads()` (or `tomllib.loads()` in Python 3.11+). ↓

fix After writing, parse the generated TOML string or file content with `tomli.loads()` within a `try-except tomli.TOMLDecodeError` block to ensure validity, especially if the input data source is untrusted or complex.

gotcha When writing TOML to a file using `tomli_w.dump()`, the file must be opened in binary write mode (`'wb'`). Using text mode (`'w'`) can lead to encoding issues (e.g., incorrect UTF-8 handling) or incorrect newline handling. ↓

fix Always open files with `mode='wb'` when using `tomli_w.dump()`: `with open('config.toml', 'wb') as f: tomli_w.dump(data, f)`.

gotcha By default, `tomli-w` avoids writing multi-line strings (using triple quotes in TOML) even if the Python string value contains newlines. This design choice aims to ensure lossless parse/write round-trips for TOML strings where exact byte representation matters. ↓

fix Be aware that strings with newlines will be output as single-line TOML strings with escaped newline characters (e.g., `\n`). If multi-line visual representation is strictly required, manual string formatting before passing to `tomli_w` or using `tomlkit` might be necessary.

gotcha `tomli-w` is exclusively for writing TOML and does not provide any functionality for parsing or reading TOML documents. ↓

fix For reading TOML, use the `tomli` library (for Python <3.11) or Python's built-in `tomllib` module (for Python 3.11+).

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.00s 17.8M

3.10 alpine (musl) - - 0.00s 17.8M

3.10 slim (glibc) wheel 1.5s 0.00s 18M

3.10 slim (glibc) - - 0.00s 18M

3.11 alpine (musl) wheel - 0.01s 19.6M

3.11 alpine (musl) - - 0.01s 19.6M

3.11 slim (glibc) wheel 1.7s 0.01s 20M

3.11 slim (glibc) - - 0.01s 20M

3.12 alpine (musl) wheel - 0.00s 11.5M

3.12 alpine (musl) - - 0.00s 11.5M

3.12 slim (glibc) wheel 1.5s 0.00s 12M

3.12 slim (glibc) - - 0.00s 12M

3.13 alpine (musl) wheel - 0.00s 11.3M

3.13 alpine (musl) - - 0.00s 11.1M

3.13 slim (glibc) wheel 1.4s 0.00s 12M

3.13 slim (glibc) - - 0.00s 12M

3.9 alpine (musl) wheel - 0.00s 17.3M

3.9 alpine (musl) - - 0.00s 17.3M

3.9 slim (glibc) wheel 1.8s 0.00s 18M

3.9 slim (glibc) - - 0.00s 18M

Imports

tomli_w
```
import tomli_w
```
Provides `dump()` for writing to files and `dumps()` for writing to strings.

Quickstart last tested: 2026-04-24

This example demonstrates how to write a Python dictionary to a TOML formatted string using `tomli_w.dumps()` and how to write it directly to a file using `tomli_w.dump()`. It includes a cleanup step to remove the generated file.

import tomli_w
import os

# Example data to write
doc = {
    "title": "My Awesome Project",
    "owner": {
        "name": "Alice Example",
        "organization": "Example Corp",
        "dob": "1979-05-27T07:32:00-08:00"
    },
    "database": {
        "server": "192.168.1.1",
        "ports": [8001, 8001, 8002],
        "connection_max": 5000,
        "enabled": True
    },
    "servers": {
        "alpha": {
            "ip": "10.0.0.1",
            "dc": "eqdc10"
        },
        "beta": {
            "ip": "10.0.0.2",
            "dc": "eqdc10"
        }
    }
}

# 1. Write to a string
toml_string = tomli_w.dumps(doc)
print("--- TOML String ---")
print(toml_string)

# 2. Write to a file
file_path = "config.toml"
try:
    with open(file_path, "wb") as f:
        tomli_w.dump(doc, f)
    print(f"\n--- TOML written to {file_path} ---")
    with open(file_path, "r") as f_read:
        print(f_read.read())
except Exception as e:
    print(f"Error writing TOML to file: {e}")
finally:
    if os.path.exists(file_path):
        os.remove(file_path) # Clean up