Install from Source

If you want to track main, contribute changes, or debug faz at the code level, install from source. For the standard install path, use Install.

Prerequisites

• git.
• Python 3.10 or newer with pip.
• (Optional) a virtualenv tool — venv, virtualenv, or uv venv. Strongly recommended; faz pulls 30+ packages.

Clone and install

git clone https://github.com/fazhq/faz.git
cd faz
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

The -e flag installs faz in editable mode — local edits in src/ take effect immediately without re-installing. The [dev] extra adds pytest and pytest-asyncio for running the test suite.

If you use uv:

git clone https://github.com/fazhq/faz.git
cd faz
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Verify

Run the test suite:

pytest

A clean install runs in a few seconds and reports all tests passing. Tests live under tests/; the project uses pytest-asyncio's auto mode (configured in pyproject.toml).

To confirm the CLI works:

faz --help

uv run faz --help

python -m faz --help

You should see the command list (init, serve, query, test, logs, policy, mcp, mcp install, add-database).

Working against the source

The same faz init workflow applies — generate a config in any directory you want and run faz serve from there:

cd ~/myproject

faz init

uv run faz init

python -m faz init

faz serve

uv run faz serve

python -m faz serve

faz looks for faz.yaml in the current working directory by default. Set FAZ_CONFIG=/path/to/faz.yaml to point elsewhere.

To run the dev server with hot reload during contributions, use uvicorn directly. Run faz init first if the working directory doesn't already have a faz.yaml — uvicorn won't generate one and the server fails to boot without it.

faz init

uv run faz init

python -m faz init

Then start uvicorn pointing at faz's ASGI app:

uvicorn faz.app:app --reload --host 127.0.0.1 --port 8787

uv run uvicorn faz.app:app --reload --host 127.0.0.1 --port 8787

python -m uvicorn faz.app:app --reload --host 127.0.0.1 --port 8787

This is functionally equivalent to faz serve but reloads on every Python file change.

Running against a different config without reinstalling

In editable installs, faz mcp install writes whatever command and args you point it at. To wire your dev build into an MCP client without polluting the global install:

faz mcp install --target claude --dry-run

uv run faz mcp install --target claude --dry-run

python -m faz mcp install --target claude --dry-run

The --dry-run flag prints the JSON config that would be written, so you can see the full command path and edit it manually if your dev environment needs different args.

Next steps