Installing

Installing

Three ways to get it, in order of how much ends up on your machine — all three run the exact same engine underneath.

flowchart TD
    Q{"How much do you want<br/>on your machine?"}
    Q --> P1["Nothing persistent"]
    Q --> P2["No Python at all"]
    Q --> P3["Reading the code"]
    P1 --> C1["uvx factfolio init"]
    P2 --> C2["download the executable for<br/>your OS, then ./factfolio init"]
    P3 --> C3["git clone && uv sync --extra dev"]

Loading

1. uvx / pip — recommended

No clone, no dependency management. uv downloads and runs it straight from PyPI, nothing installed persistently.

uvx factfolio init
uvx factfolio report
# or: pip install factfolio && factfolio init

Reads and writes wherever you run it from — cd into a folder for this portfolio first, the same way you'd use git or terraform.

2. Standalone executable — no Python at all

Download factfolio (or factfolio.exe on Windows) for your OS from the latest release, make it executable, run it:

chmod +x factfolio-macos-arm64
./factfolio-macos-arm64 init

Single file, every dependency baked in — nothing else to install. Double-clicking it with no arguments shows an instant status snapshot (if you already have holdings in place) and the numbered next steps — plain terminal output, identical on every platform, no window to vanish before you can read it.

Your OS will warn you before running it. These builds aren't code-signed — see FAQ for why that warning appears and how to get past it safely.

3. Clone + dev setup

For contributing, or reading/customising the code:

git clone https://github.com/pankajads/factfolio.git
cd factfolio
uv sync --extra dev
uv run factfolio init

See CONTRIBUTING.md in the repo for the full contributor workflow.

Every path still needs one more thing

factfolio report and factfolio chat need the separate claude CLI logged in (claude login) or ANTHROPIC_API_KEY set — no install method above changes that. factfolio status, validate, cron, and estimate-dates need neither; they're pure deterministic Python. See FAQ.