---
title: Installation
review-state: drafting
last-human-review: "2026-06-03"
depends-on:
  - pyproject.toml
  - src/pytyche/setup.py
owner: tradcliffe
---

# Installation

## Recommended: with GPU JAX

```bash
uv add 'pytyche[gpu]'
```

Or with pip: `pip install 'pytyche[gpu]'`.

The `[gpu]` extra installs the CUDA-12 JAX wheel (Linux only). The
library is designed around GPU execution at scale — the per-round joint
hurdle fit hits 4.5–8.6× speedup at n=750k versus the CPU StochTree
backend, and the single-channel paths hit 17–63× from n=250k through
n=2M (part of the headline 5×–60× range). The calibration loop (hundreds
of fits per SBC sweep) only becomes practical on a GPU.

## CPU-only

```bash
uv add pytyche
```

The base install is a fully functional CPU library — fine for small
experiments, prototyping, and the testable subset of the tutorials.
The first model fit in a process without a CUDA device emits a
`UserWarning` recommending the `[gpu]` extra; it fires once per process.
If CPU execution is what you want (CI, laptops, small data), silence it
with the `PYTYCHE_SUPPRESS_GPU_WARNING=1` environment variable or a
standard `warnings.filterwarnings(...)` rule.

## Development install (editable, all extras)

The canonical setup for working on the library itself:

```bash
git clone --recurse-submodules https://gitlab.com/tradcliffe2/tyche
cd tyche
uv sync --all-extras
```

This pulls the [bartz](https://github.com/Gattocrucco/bartz) fork as
a submodule (the GPU BART kernels pytyche fits on top of). The
`--all-extras` flag installs the `docs`, `dev`, `gpu`, and
`cpu-bcf` extras together — the canonical setup for working on the
library itself.

:::{note}
`uv sync --extra <name>` removes packages from extras you don't
list — that's `uv`'s documented behavior but a footgun in this repo
because the editable `[tool.uv.sources]` for bartz + stochtree get
clobbered. **Always use `uv sync --all-extras`** for environment
work in this repo, or explicitly name every extra you need.
:::

## Verify

```python
import pytyche as pt

pt.check_setup()
```

Prints the installed pytyche and bartz versions, the JAX devices it
can see, whether CUDA is available, and the bundled calibration
artifacts — and returns the same content as a structured
`SetupReport`. If CUDA is missing, `recommended_install` carries the
command that fixes it. For JAX/CUDA configuration problems, see the
[JAX installation guide](https://docs.jax.dev/en/latest/installation.html)
for platform-specific troubleshooting.