{"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,"last_verified":"2026-05-12T19:49:47.496Z","next_check":"2026-06-27T00:00:00.000Z","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,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.2.0","cli_name":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.3,"disk_size":"17.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.3,"disk_size":"17.8M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0,"mem_mb":0.3,"disk_size":"18M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.3,"disk_size":"18M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"19.6M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"19.6M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.1,"disk_size":"11.5M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.1,"disk_size":"11.5M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0,"mem_mb":0.1,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.1,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.3,"disk_size":"11.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.3,"disk_size":"11.1M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":0,"mem_mb":0.1,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.1,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.3,"disk_size":"17.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.3,"disk_size":"17.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0,"mem_mb":0.3,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.3,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}