footman

A task runner with the soul of duty and the UX of typer: typed function signatures become real flags and positionals, modules become nested command groups, independent tasks run in parallel by default, and shell completion answers from a cached manifest in ~30 ms — without importing your code.

Ships two console scripts, footman and the two-letter fm. Zero runtime dependencies. Python 3.11+.

[!NOTE] Beta. footman is pre-1.0: the surface is settling, but minor versions may still include breaking changes — always called out in the changelog, never in a patch release. Pin the minor (footman~=0.38.0) if you build on it. The written stability promise lands with 1.0 — the road there is in ROADMAP.md.

Why

duty gets a lot right — the run() capture model, the decorator ergonomics — and footman keeps those ideas. Where it pushes is the parts that compound: completion served from a cache instead of re-importing your project on every Tab (~13× faster, measured), eager type and choice validation with errors that teach, a DAG scheduler that runs independent tasks concurrently (the same four-step check lands ~3.5× sooner than duty or invoke, measured) with true fail-fast that kills in-flight work on the first failure, runnable command groups and parameter forwarding that make composite commands like fm lint and check real commands, a monorepo task cascade that merges a tasks.py per directory, and a first-party story for testing your tasks. The receipts live in the comparison — every number reproducible from comparison/.

Taste

uv add --dev footman        # or: pip install footman

# tasks.py
from footman import task, group, run
from toolroom import pytest, ruff

@task
def lint(fix: bool = False):
    "Run ruff over the project."
    ruff.check("src", fix=fix)

@task(pre=[lint])
def test(*pytest_args):
    "Run the test suite (extra args after --)."
    pytest(*pytest_args)

docs = group("docs", help="Documentation")

@docs.task(infinite=True)
def serve(port: int = 8000):
    "Serve the docs locally."
    run(f"mkdocs serve -a localhost:{port}")

$ fm lint --fix
$ fm lint test docs.serve --port=8001   # one chain; independent tasks run in parallel
$ fm test -- -k grammar -x              # everything after -- goes to pytest
$ fm deploy produ
fm: deploy: <target> must be one of dev|staging|prod (got 'produ') — did you mean 'prod'?
$ fm --install-completion               # detects your shell; TAB answers in ~30 ms

One file, dependencies included

A tasks file can declare what it needs inline (PEP 723), and then it needs no project at all — drop it in any directory and run it:

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["footman", "httpx"]
# ///
import footman
from footman import task

@task
def health(url: str = "https://example.com"):
    "Check a deployment is up."
    import httpx
    print(httpx.get(url).status_code)

if __name__ == "__main__":
    footman.main(__file__)

fm health builds that environment once and runs inside it; chmod +x and ./deploy.py health works with no runner installed at all. Checked into a project that pins footman, the header is simply ignored and the file runs on the project's dependencies — portable and at home.

Learn more

Documentation — start with Getting started, then the good parts: typed signatures · chaining & parallelism · monorepos · composing tasks · running tools · testing your tasks · completion · CI & automation · comparison with duty / invoke / poe / typer

MIT licensed. The road to 1.0 lives in ROADMAP.md.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

footman-0.38.1.tar.gz (346.9 kB view details)

Uploaded Aug 10, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

footman-0.38.1-py3-none-any.whl (365.9 kB view details)

Uploaded Aug 10, 2026 Python 3

File details

Details for the file footman-0.38.1.tar.gz.

File metadata

Download URL: footman-0.38.1.tar.gz
Upload date: Aug 10, 2026
Size: 346.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for footman-0.38.1.tar.gz
Algorithm	Hash digest
SHA256	`e0a30a6deed9b22ca686c81bd6b6ba2792f85b2175dcfd326716fca5b9b1670d`
MD5	`45ad54709cf14a4e787903a918f9300f`
BLAKE2b-256	`0f87680bf1ce11cbfc56c777a8dcf633d6a278f6db3da0a52fdbbd1360552c13`

See more details on using hashes here.

Provenance

The following attestation bundles were made for footman-0.38.1.tar.gz:

Publisher: release.yml on willemkokke/footman

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: footman-0.38.1.tar.gz
- Subject digest: e0a30a6deed9b22ca686c81bd6b6ba2792f85b2175dcfd326716fca5b9b1670d
- Sigstore transparency entry: 2408262661
- Sigstore integration time: Aug 10, 2026
Source repository:
- Permalink: willemkokke/footman@789af3f7dde715087501b2820d566e5ae61d39f4
- Branch / Tag: refs/tags/v0.38.1
- Owner: https://github.com/willemkokke
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@789af3f7dde715087501b2820d566e5ae61d39f4
- Trigger Event: push