{"id":812,"library":"tomli-w","title":"Tomli-W: A Minimal TOML Writer","description":"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.","status":"active","version":"1.2.0","language":"python","source_language":"en","source_url":"https://github.com/hukkin/tomli-w","tags":["TOML","configuration","writer","serialization","toml-w"],"install":[{"cmd":"pip install tomli-w","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"Provides `dump()` for writing to files and `dumps()` for writing to strings.","symbol":"tomli_w","correct":"import tomli_w"}],"quickstart":{"code":"import tomli_w\nimport os\n\n# Example data to write\ndoc = {\n    \"title\": \"My Awesome Project\",\n    \"owner\": {\n        \"name\": \"Alice Example\",\n        \"organization\": \"Example Corp\",\n        \"dob\": \"1979-05-27T07:32:00-08:00\"\n    },\n    \"database\": {\n        \"server\": \"192.168.1.1\",\n        \"ports\": [8001, 8001, 8002],\n        \"connection_max\": 5000,\n        \"enabled\": True\n    },\n    \"servers\": {\n        \"alpha\": {\n            \"ip\": \"10.0.0.1\",\n            \"dc\": \"eqdc10\"\n        },\n        \"beta\": {\n            \"ip\": \"10.0.0.2\",\n            \"dc\": \"eqdc10\"\n        }\n    }\n}\n\n# 1. Write to a string\ntoml_string = tomli_w.dumps(doc)\nprint(\"--- TOML String ---\")\nprint(toml_string)\n\n# 2. Write to a file\nfile_path = \"config.toml\"\ntry:\n    with open(file_path, \"wb\") as f:\n        tomli_w.dump(doc, f)\n    print(f\"\\n--- TOML written to {file_path} ---\")\n    with open(file_path, \"r\") as f_read:\n        print(f_read.read())\nexcept Exception as e:\n    print(f\"Error writing TOML to file: {e}\")\nfinally:\n    if os.path.exists(file_path):\n        os.remove(file_path) # Clean up","lang":"python","description":"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."},"warnings":[{"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.","message":"`tomli-w` requires Python 3.9 or newer. Attempts to use it on older Python versions will result in an `ImportError` or `SyntaxError`.","severity":"breaking","affected_versions":"<1.0.0 (older versions of `tomli`, counterpart, had Python 3.6+ support, but `tomli-w` consistently targets newer Python versions)."},{"fix":"If style preservation is critical, evaluate `tomlkit`. Otherwise, ensure your workflow does not depend on output TOML mirroring input formatting precisely.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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+).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always open files with `mode='wb'` when using `tomli_w.dump()`: `with open('config.toml', 'wb') as f: tomli_w.dump(data, f)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For reading TOML, use the `tomli` library (for Python <3.11) or Python's built-in `tomllib` module (for Python 3.11+).","message":"`tomli-w` is exclusively for writing TOML and does not provide any functionality for parsing or reading TOML documents.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'3.11':51 'act':27 'activ':71 'also':40 'basi':42 'compat':55 'configur':77 'correct':64 'counterpart':33 'design':16 'document':25 'focus':60 'fulli':54 'languag':24 'librari':15,47,68 'maintain':69 'minim':5,23 'modul':48 'obvious':22 'output':66 'parser':37 'period':74 'pure':13 'python':14,50 'serial':79 'simplic':62 'standard':46 'status':72 'tom':2,9,20,36 'toml':6,19,57,76,81 'toml-w':80 'tomli-w':1,8 'tomllib':45 'updat':75 'v1.0.0':58 'w':3,10,82 'write':18,31 'write-on':30 'writer':7,78","created_at":"2026-03-29T04:22:46.286935+00:00","updated_at":"2026-04-16T23:01:40.536173+00:00","problems":[{"fix":"Install the library using pip: `pip install tomli-w`","cause":"The `tomli-w` package is not installed in the current Python environment, or the module name `tomli_w` is misspelled.","error":"ModuleNotFoundError: No module named 'tomli_w'"},{"fix":"Use the `tomli` library (or `tomllib` in Python 3.11+) to read TOML files, e.g., `import tomli` then `tomli.load(fp)`.","cause":"`tomli-w` is a write-only library designed for creating TOML documents and does not include functions for parsing (reading) TOML files.","error":"AttributeError: module 'tomli_w' has no attribute 'load'"},{"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.","cause":"`tomli-w` encountered a Python object type (like a `set` or custom class instance) that cannot be directly represented in the TOML specification.","error":"TypeError: Object of type set is not TOML serializable"},{"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)`.","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.","error":"AttributeError: 'str' object has no attribute 'write'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.2.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/hukkin/tomli-w","docs":null,"changelog":"https://github.com/hukkin/tomli-w/blob/master/CHANGELOG.md","pypi":"https://pypi.org/project/tomli-w/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}