Skip to content

The unified Python development toolchain

Pyfaro is a fast, Rust-built command-line tool: one CLI over uv, Ruff, ty and pytest, from creating a project to running its quality checks and tests.

Get started Why Pyfaro? GitHub

See it work

A terminal recording: pyfaro create fastapi acme-api, then pyfaro sync, pyfaro check and pyfaro test, which all pass. pyfaro dev serves the app with Uvicorn, reloads it after a source file changes and stops on Ctrl-C with exit status 130.

The same commands as text:

pyfaro create fastapi acme-api   # scaffold a typed FastAPI project
cd acme-api
pyfaro sync                      # create .venv and uv.lock
pyfaro check                     # format check, lint, type check
pyfaro test                      # run pytest
pyfaro dev                       # Uvicorn with reload; Ctrl-C stops the whole tree

Recorded on Linux with 0.5.0-beta.1, from a script that types the commands and runs the real binary. The edit that makes the server reload is made by that script, not typed.

Install

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

The script verifies the download against SHA256SUMS, installs to ~/.local/bin and changes nothing else. Prefer to read it first? Download, inspect, then run it.

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

The script verifies the download against SHA256SUMS and installs to %USERPROFILE%\.local\bin.

uv tool install pyfaro
pyfaro --version

Also pipx install pyfaro or pip install pyfaro. No Rust toolchain is needed; the wheels hold the same pyfaro executable (from 0.5.0b1). While every release is a pre-release, installers pick the newest one on their own. See Installation to pin a version.

Requires Rust 1.90 or newer.

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

The explicit version is needed while every release is a pre-release.

Download the archive for your platform from GitHub Releases (Linux x86_64 and aarch64, macOS arm64 and x86_64, Windows x86_64), check it against SHA256SUMS, and put pyfaro on your PATH.

Pyfaro needs uv 0.9.26 or newer at runtime and never installs it for you. See Installation for details, upgrading and uninstalling.

What you can do

  • Create

    Start a library, CLI or FastAPI project, or bring an existing one under Pyfaro with init.

    create · init

  • Dependencies and environments

    sync builds the virtual environment and lockfile; add and remove edit dependencies.

    sync · add and remove

  • Run

    Run commands inside the project environment, without activating it.

    run

  • Dev server

    dev runs your FastAPI app with Uvicorn and reload, supervised, and stops the whole process tree on Ctrl-C.

    dev · FastAPI guide

  • Tasks

    Name the commands you run often in [tool.pyfaro.tasks] and run them with pyfaro run <task>.

    tasks

  • Quality gate

    lint, fmt and type run Ruff and ty; check runs them together.

    check

  • Tests

    Run the project's pytest suite through one command.

    test

  • Build

    build produces a source distribution and a wheel through uv build, with the build backend your project declares.

    build

  • Diagnostics

    doctor reports on the toolchain; python and tools inspect interpreters and tool versions.

    doctor · python · tools

How it works

Pyfaro does not reimplement these tools. It finds your project, then calls the right tool for each job and reports the result.

flowchart LR
    you([you]) --> pyfaro[pyfaro]
    pyfaro --> uv[uv<br/>environments, locks]
    pyfaro --> ruff[Ruff<br/>lint, format]
    pyfaro --> ty[ty<br/>type check]
    pyfaro --> pytest[pytest<br/>tests]

Read more in How it works. Wondering why not just uv, a Makefile or a task runner? See Why Pyfaro.

Status

Beta software

beta The latest published version is 0.5.0-beta.1, the first public beta. Interfaces may still change before 1.0. Commands that are planned but not implemented yet, such as workspaces, are not documented as available.

Feedback shapes the beta: ask a question or share an idea in GitHub Discussions, report a bug with the bug report form, or tell us how it went.

Where to go next:

  • Getting started: install Pyfaro and run your first commands.
  • Why Pyfaro: what it adds on top of uv, how it compares with other tools, and what it does not do yet.
  • Commands: one tutorial per command.
  • Workflows: end-to-end recipes, including a FastAPI app.
  • Reference: command line, environment variables, tested versions.