tox-toml-fmt

What it is and what it does

tox-toml-fmt is a command-line tool and Python library that reformats tox.toml files according to a fixed set of opinionated rules, similar to how black formats Python code. It normalizes string quotes, key formatting, array layout, and table structure while preserving comments. The tool supports minimal configuration (column width, indentation, pinned environments) and can be used standalone, integrated as a pre-commit hook, or called programmatically from Python code.

The formatter runs on Python 3.10 and higher and is distributed as compiled wheels for multiple platforms. It depends on toml-fmt-common for shared formatting logic. Recent updates include support for free-threaded Python wheels and fixes for empty table handling.

Use it for:

• Enforce consistent formatting across tox.toml files in a monorepo or team project
• Integrate as a pre-commit hook to automatically format tox.toml on every commit
• Programmatically format tox.toml files in build or CI/CD automation scripts
• Standardize tox configuration style without manual configuration of dozens of formatting rules
• Reduce diff noise in code reviews by applying deterministic formatting rules

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Formats tox.toml files with consistent style and comment preservation, applying opinionated rules similar to black for Python code.

Yes, if you manage tox.toml files and want consistent formatting with minimal configuration overhead. The tool is actively maintained, has no known vulnerabilities, and uses a permissive license. Install via pipx or uv to avoid dependency conflicts. Not necessary if you have no tox.toml files or prefer manual formatting.

Install

tox-toml-fmt on PyPI

pip install tox-toml-fmt

uv add tox-toml-fmt

poetry add tox-toml-fmt

Installing tox-toml-fmt

Before you install

Medium install friction due to compiled wheels across multiple platforms and Python versions (3.10+). Active maintenance with recent releases; last commit 2026-08-12 and 85 repository stars indicate ongoing support.

License in practice

MIT license (permissive) allows use in most projects without restriction.

Quickstart

# Install via pipx (recommended)
pipx install tox-toml-fmt

# Or as a Python module
from tox_toml_fmt import run
exit_code = run(["path/to/tox.toml"])

Requires Python 3.10 or higher; recommended installation via pipx or uv to avoid system-wide dependency conflicts.

Verify before relying

• Exact behavior differences between CLI, pre-commit hook, and programmatic Python API usage
• Performance characteristics on large or deeply nested tox.toml files
• Compatibility with non-standard TOML extensions or vendor-specific tox configurations

Package facts

Evidence: tox_toml_fmt-1.9.3-cp310-abi3-macosx_10_12_x86_64.whl; tox_toml_fmt-1.9.3-cp310-abi3-macosx_11_0_arm64.whl; tox_toml_fmt-1.9.3-cp310-abi3-manylinux_2_28_aarch64.whl; tox_toml_fmt-1.9.3-cp310-abi3-manylinux_2_28_x86_64.whl; tox_toml_fmt-1.9.3-cp310-abi3-manylinux_2_31_riscv64.whl; tox_toml_fmt-1.9.3-cp310-abi3-musllinux_1_2_x86_64.whl; tox_toml_fmt-1.9.3-cp310-abi3-win_amd64.whl; tox_toml_fmt-1.9.3-cp313-cp313t-macosx_10_12_x86_64.whl; tox_toml_fmt-1.9.3-cp313-cp313t-macosx_11_0_arm64.whl; tox_toml_fmt-1.9.3-cp313-cp313t-manylinux_2_28_aarch64.whl; tox_toml_fmt-1.9.3-cp313-cp313t-manylinux_2_28_x86_64.whl; tox_toml_fmt-1.9.3-cp313-cp313t-musllinux_1_2_x86_64.whl; tox_toml_fmt-1.9.3-cp313-cp313t-win_amd64.whl; tox_toml_fmt-1.9.3-cp314-cp314t-macosx_10_12_x86_64.whl; tox_toml_fmt-1.9.3-cp314-cp314t-macosx_11_0_arm64.whl; tox_toml_fmt-1.9.3-cp314-cp314t-manylinux_2_28_aarch64.whl; tox_toml_fmt-1.9.3-cp314-cp314t-manylinux_2_28_x86_64.whl; tox_toml_fmt-1.9.3-cp314-cp314t-musllinux_1_2_x86_64.whl; tox_toml_fmt-1.9.3-cp314-cp314t-win_amd64.whl; tox_toml_fmt-1.9.3-cp315-cp315t-macosx_10_12_x86_64.whl

Keywords: format, pyproject

Tags

More Build Tools packages