wox 0.1.0

A declarative CLI that runs reproducible tasks inside isolated Python environments

wox

Wox is a lightweight Python task automation tool designed to simplify development workflows. It allows you to run tasks in isolated Python environments, manage dependencies, and execute commands exactly as you would in your terminal.

With wox, you can:

• Run tests across multiple Python versions effortlessly.
• Automate common tasks like linting, formatting, or documentation generation.
• Execute any shell command or entry point from Python or other languages (Java, C, JavaScript, …) in a controlled environment.
• Keep your workspace clean with .wox, where virtual environments and logs are automatically managed.

Wox gives you full transparency and control over your automation: no hidden behaviors, no surprises. You declare your tasks in a wox.toml or pyproject.toml file, and wox handles the rest.

Example

As an example, here is how wox ensures its own compatibility across Python versions:

[wox_configuration]
recreate_envs = false

[testing]
envlist = ['py310', 'py311', 'py312', 'py313', 'py314']
deps = ['-r requirements.txt', '-e .']
commands = ['python -B -m pytest']

Check more examples on the Quickstart section of the documentation.

Quickstart

Install with pip:

pip install wox

Or use pipx to run wox without Python virtual environments:

pipx install wox

If you’re a uv enthusiast, you can run it directly thanks to uvx, the alias for uv tool run:

uvx wox

Then, create a task in your wox.toml and run it with:

wox

Documentation

Check the documentation for detailed guides and examples.

Why wox?

At some point, I needed to validate a framework against Python 3.6. While the code itself was still compatible, the tooling ecosystem had already started to move on. In particular, virtualenv had dropped support for creating environments targeting Python versions older than 3.7.

This raised a broader concern: if tooling stops supporting older interpreters today, what guarantees do we have that it will not move further tomorrow?

In many critical environments, Python versions do not evolve at the same pace as the ecosystem. Long-term support constraints, certification processes, or operational risks often require running stable - and sometimes old - Python interpreters for years.

Rather than working around this limitation, wox emerged from a simple requirement: executing tasks against explicitly selected Python interpreters, in a fully isolated and reproducible way, without relying on assumptions made by the surrounding tooling.

As development progressed, something became apparent: wox was sufficiently abstract and robust to support use cases far beyond my original problem.

Testing across Python versions, comparing custom builds, benchmarking interpreters, onboarding new developers, running non-Python tooling — none of these required special handling. They naturally fell out of the same execution model.

Wox did not grow by accumulating features, but by revealing the consequences of its design. New use cases emerged not because they were planned, but because the underlying abstraction held.

Contribution

Have an idea to improve wox and don't know how to give it a go? Check the CONTRIBUTION.md and propose your feature with a merge request.