Get Started¶

Define custom scripts in your pyproject.toml and easily run them with this dependency free tool. This tool is both inspired by and similar to NPM Scripts .

For a more detailed implementation (requires external installation) use Taskfile .

To get started see the Quick Start section or check out the Features.

uv tool install toml-run

uv add --dev toml-run

pip install toml-run

pip install --group dev toml-run

brew install cssnr/tap/toml-run

[tool.scripts]
build = "uv run hatch build"

run build

If you run into any issues or have any questions, support is available.

Features¶

• Define scripts in your pyproject.toml
• Easily run scripts with run [name]
• Cross-platform support using subprocess
• Supports pre and post scripts
• Supports multiple commands per script
• Pass additional arguments to scripts
• Automatically finds the pyproject.toml
• Runs scripts relative to the root directory
• Evaluate python code

For more details see the full reference.

Quick Start¶

First, install the package from PyPi or GitHub .

uv tool install toml-run

uv add --dev toml-run

pip install toml-run

pip install --group dev toml-run

brew install cssnr/tap/toml-run

Then, add some scripts to the pyproject.toml.

[tool.scripts]
clean = "rm -rf dist"
build = "run clean && uv run hatch build"
prelint = "echo always runs before lint"
lint = ["uv run ruff check .", "uv run ty check ."]
postlint = "echo always runs after lint"

Finally, run a script.

run build

Or, run without installing using astral-sh/uv .

uvx toml-run build

Script Reference

Usage Reference