---
id: tox-toml-fmt
version: "1.9.3"
license: unclear
license_treatment: permissive
maintenance: active
---

# tox-toml-fmt — Format your pyproject.toml file

License: permissive · Maintenance: active · Downloads: 242.8K/mo

## 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 above — 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

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

- License: not declared (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 242.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

tox.toml formatter, format toml files, consistent toml style, tox configuration formatter, toml code formatter, pyproject.toml formatter, opinionated toml formatting, formatter, toml, tox

[View on SkillFed](https://skillfed.io/packages/tox-toml-fmt) · [View on PyPI](https://pypi.org/project/tox-toml-fmt/)