pyfaro 0.5.0b1

One command-line workflow for Python projects.
Fast, opinionated, built with Rust.

Pyfaro brings project creation, dependencies, Python versions, linting, formatting, type checking and testing under a single pyfaro command. It does not replace the tools you already trust: it orchestrates uv, Ruff, ty and pytest behind one consistent, scriptable interface, so a new contributor, a CI job and a git hook all run exactly the same commands.

Beta software. Pyfaro is under active development and interfaces may still change before 1.0. See Project status.

Why Pyfaro

• One entry point. create, sync, add, check, test and more, instead of remembering four tools and their flags.
• pyfaro check is your quality gate. Format check, lint and type check in one run, with a clear summary and an honest exit code. It writes files only when you pass --fix.
• From scaffold to running server. pyfaro create fastapi generates a typed FastAPI app, and pyfaro dev runs it with Uvicorn and auto-reload, supervised: Ctrl-C stops the whole process tree and nothing is left behind.
• Tasks without a second tool. Name the commands you run often in [tool.pyfaro.tasks] and run them with pyfaro run <task>, with no implicit shell and the same behavior on Linux, macOS and Windows.
• No second ecosystem. Standard pyproject.toml and uv's uv.lock. Pyfaro adds a tiny [tool.pyfaro] table and leaves everything else alone.
• Adopt it in place. pyfaro init previews what it would change before touching your existing project.
• Predictable by design. Nothing syncs, installs or downloads behind your back. doctor explains what is wrong and how to fix it.
• A single native binary written in Rust.

Demo

$ pyfaro create lib textkit
Created library at ~/projects/textkit
$ cd textkit
$ pyfaro sync
Using CPython 3.13.11
Creating virtual environment at: .venv
Resolved 12 packages in 93ms
...
$ pyfaro check
4 files already formatted
All checks passed!
All checks passed!

== pyfaro check summary ==
format: ok
lint: ok
type: ok
check: ok
$ pyfaro test
============================= test session starts ==============================
...
collected 1 item

tests/test_library.py .                                                  [100%]

============================== 1 passed in 0.01s ===============================

Installation

Pyfaro needs uv 0.9.26 or newer at runtime. Pyfaro never installs uv or Python for you.

Install script for Linux and macOS. It downloads the newest release for your machine over HTTPS, verifies it against SHA256SUMS and installs it to ~/.local/bin, without sudo and without touching your shell profile:

curl --proto '=https' --tlsv1.2 -LsSf https://pyfaro.dev/install.sh | sh

On Windows, in PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://pyfaro.dev/install.ps1 | iex"

Prefer to read a script before running it? Download it first with curl ... -o install.sh (or irm ... -OutFile install.ps1), inspect it, then run the file. Run the script again to upgrade; set PYFARO_VERSION to pin a version.

From PyPI, without a Rust toolchain (from 0.5.0b1; Pyfaro's 0.5.0-beta.1 is 0.5.0b1 in Python's version format):

uv tool install pyfaro      # or: pipx install pyfaro / pip install pyfaro

Every published version is still a pre-release, and installers fall back to the newest pre-release when there is no stable one, so these commands work as they are. To pin one, name it (uv tool install pyfaro==0.5.0b1). Once a stable version exists, add --prerelease allow (uv) or --pre (pip, and pipx install --pip-args=--pre) to keep following the pre-releases.

From crates.io (Rust 1.90 or newer):

cargo install pyfaro --version 0.5.0-beta.1 --locked

While every published version is a pre-release, Cargo needs the explicit --version; a bare cargo install pyfaro finds no stable release.

Prebuilt binaries for Linux (x86_64, aarch64), macOS (arm64, x86_64) and Windows (x86_64) are attached to each GitHub Release, together with a SHA256SUMS file and a build provenance attestation for each asset. The archives are not code-signed: verify them against SHA256SUMS (and, with the GitHub CLI, gh attestation verify <file> --repo pyfaro/pyfaro), extract, and put pyfaro on your PATH.

Check the installation, and the toolchain around it:

pyfaro --version
pyfaro doctor      # explains a missing or outdated uv and how to fix it

More detail: Installation.

Quick start

pyfaro create lib my-lib      # or: create cli my-app, create fastapi my-api
cd my-lib
pyfaro sync                   # create .venv and uv.lock
pyfaro add "requests>=2"      # then: pyfaro sync
pyfaro check                  # format check, lint, type check
pyfaro test                   # run pytest

Building an API? A FastAPI project is ready to serve right after sync (published in 0.4.0-alpha.1):

pyfaro create fastapi my-api
cd my-api
pyfaro sync
pyfaro dev                    # Uvicorn with reload on http://127.0.0.1:8000

The FastAPI guide goes from install to a running app and a passing CI workflow.

Adopting an existing project? Preview first, then apply (Linux only for now):

pyfaro init                   # preview, writes nothing
pyfaro init --apply

Walk through it step by step in First steps, or follow a full workflow.

Commands

Recipes live in the workflows section: a new library, a new CLI, a FastAPI app, adopting an existing project, CI and troubleshooting.

How it works

Pyfaro owns the command line, configuration, orchestration and diagnostics. Everything else stays with the tool built for it.

There is no second resolver, lock file format, package manager, linter or test engine: Pyfaro calls the real tools and passes their output and exit status through. Read more in How it works and the architecture decision record.

Project status

Pyfaro is beta. The latest version is 0.5.0-beta.1 (0.5.0b1 on PyPI). Interfaces may still change before 1.0.

• Tested versions: uv 0.9.26, Ruff 0.16.10, ty 0.0.85, pytest 9.1.1.
• Platforms: Linux, macOS and Windows are built and tested in CI. init --apply is Linux-only for now; on macOS and Windows init previews but does not apply.
• Implemented: create, init, sync, add, remove, run, dev, python, build, tools, doctor, lint, fmt, type, check, test and completions.

See the changelog for what each release contains.

Roadmap

Planned, not yet available: workspaces. Milestones are planning targets, not release announcements. Follow the roadmap board, milestones and issues.

Contributing

Contributions are welcome. Read the contribution guide and the code of conduct; report vulnerabilities as described in the security policy. Questions are welcome in Discussions.

To build from source you need Rust (the toolchain is pinned in rust-toolchain.toml):

git clone https://github.com/pyfaro/pyfaro.git
cd pyfaro
cargo build --locked
cargo run --locked -- --help

License

Pyfaro is licensed under Apache-2.0.