# Installation

valgebra publishes prebuilt wheels to PyPI, so the common path needs no Rust toolchain. Building from source is the fallback for development or an unsupported platform; it is a Rust extension built with [maturin](<https://www.maturin.rs/>), which requires a Rust toolchain.

## From PyPI

With **Python** 3.11 or newer:

```
pip install valgebra
# or
uv add valgebra
```

valgebra has no runtime dependencies. The examples in these pages import packages it does not:

- [annotated-types](<https://pypi.org/project/annotated-types/>), whose markers most refinement examples are written with. valgebra reads the markers structurally, never by importing that package.
- [typing-extensions](<https://pypi.org/project/typing-extensions/>), for the forms an example spells from it where an older Python's `typing` lacks them.
- [pytest](<https://pypi.org/project/pytest/>), which the examples showing a refusal use.
- [FastAPI](<https://pypi.org/project/fastapi/>) and [pydantic](<https://pypi.org/project/pydantic/>), which the [FastAPI recipe](<https://ppigazzini.github.io/valgebra/get-started/recipes/index.md#a-field-of-a-fastapi-request>) uses.
- [numpy](<https://pypi.org/project/numpy/>), which the [arrays section](<https://ppigazzini.github.io/valgebra/explanation/boundaries/index.md#it-reads-an-array-through-what-the-array-exposes>) of the boundaries page uses.

Install them to run the examples as printed:

```
pip install annotated-types typing-extensions pytest fastapi pydantic numpy
```

Wheels are published for every supported CPython, 3.11 through 3.15, on Linux (manylinux and musllinux, x86\_64 and aarch64), macOS (Intel and Apple silicon) and Windows x64, and from 3.12 on Windows arm64. Free-threaded CPython 3.14 and 3.15 have wheels on manylinux, musllinux, macOS and Windows x64, and [PyPy 3.11 and 3.12](<#pypy>) on manylinux. Free-threaded support starts at 3.14t; the earlier 3.13 free-threaded build is not a target.

## From source

Building from source additionally requires:

- A stable **Rust** toolchain (edition 2024, MSRV 1.88) via [rustup](<https://rustup.rs/>).
- [**uv**](<https://docs.astral.sh/uv/>) (recommended) for the environment and the build.

```
git clone https://github.com/ppigazzini/valgebra && cd valgebra
uv sync                 # create .venv and install the dev dependencies
uv run --no-sync maturin develop --uv  # build the Rust extension into the venv
```

## Verify it works

```
import valgebra
from valgebra import Validator

print(valgebra.__version__)
assert Validator(int).is_valid(7)
```

## PyPy

PyPy 8.0 is the target, on Python 3.11 and 3.12 and on Linux. A wheel is published for each on manylinux x86\_64 and aarch64, tagged `pp80`, and an installer matches that tag exactly. So PyPy 7.3, and PyPy on musl, macOS or Windows, install from the source distribution, which needs a Rust toolchain, and no lane here runs them. Every push builds the extension against both series, imports it, and runs the product suite there, with the repository checks whose answer is the interpreter's. Both halves are needed, because the C API PyPy offers is not CPython's: an extension there runs through `cpyext`, which carries the limited API and not every static type object CPython exports, so naming one of those links fine and fails at `import` — and `cpyext` also *answers* differently, which no import can show. The PyPy wheels are plain release builds, where the glibc Linux, macOS and Windows x64 CPython wheels are profile-guided: a profiled extension runs out of the native stack budget `cpyext` sizes from the recursion limit before the walk reaches its own depth bound, and the process dies where the plain build reports the bound. The release runs the product suite on every wheel set it ships, on each set's floor, newest and free-threaded interpreters, and imports and checks the releases between -- the `smoke` and `smoke-musl` matrices in `.github/workflows/release.yml` name them -- and each PyPy wheel on its own series, not only on the one the push lane builds. The musllinux sets run in Alpine containers, the free-threaded wheels on uv's musl build of each release, since the Docker library publishes no free-threaded image (`docs/dev/releasing.md` in the repository).

One promise [What it cannot do](<https://ppigazzini.github.io/valgebra/explanation/boundaries/index.md#it-holds-what-its-schema-names-and-lets-go-of-it>) makes holds differently there. A validator releases the classes, enums and predicates its schema names when nothing else holds them, and on PyPy it cannot: `cpyext` builds a `PyTypeObject` proxy for every class an extension is shown and never frees it, so a class is kept alive from the first validator that reads it, whatever that validator does afterwards. A long-running process that compiles a schema over a *throwaway* class per request grows there and does not on CPython. Nothing in valgebra can change this, and the suite's four lifetime cases say so on PyPy rather than claiming to pass.

And one call CPython refuses, PyPy answers. `object.__new__(Validator)` makes a validator whose schema was never compiled, which on PyPy 8.0 admits every value. CPython's `object.__new__` refuses a class with a constructor of its own; PyPy's does not ask, and no code of valgebra's runs to refuse it. Build a validator by calling `Validator`.

And one kind of value no extension can be shown there. `cpyext` hands an extension an object by attaching it, and attaching an instance of a `dict`, `tuple` or `bytes` subclass calls the subclass's own `__len__`. Where that raises, nothing valgebra reads survives it: passed as the value itself, the object raises the subclass's exception from `validate` or `is_valid`; held in a list, a dict, a set or a record's field, it ends the process where the walk reads it, or, in a list whose items the walk does not read (`list[object]`), raises `SystemError`. CPython reads the storage and asks the type nothing, so there each such value is checked by what it holds.

And one relation decides less there. A type defined in C, such as `complex`, lays down an instance layout no class can combine with `int`'s, and on CPython valgebra reads it off the size of the type's instance: `intersection(complex, int).is_empty()` is `True`. PyPy refuses the same classes but names no size, so there that meet is not called empty, and `Validator(complex).relation_to(complement(int))` is `undecided`.

## Free-threaded CPython

On a free-threaded interpreter a validator is immutable and shares no mutable walk state, so object validation runs in parallel with the interpreter lock disabled. The JSON path takes one lock: its string parser takes an interned-string cache from a pool behind a lock and puts it back after the parse, so concurrent `validate_json`/`load` calls contend only on that hand-off, and neither the parse nor the walk holds it.

Three things read differently there:

- **Threads checking one shared value contend for it.** The walk takes each container's own lock to read an element, so threads validating one shared container serialize on it, where threads each holding their own copy run in parallel. Give each thread its own value, or check a shared value once.
- **Forking a process whose threads are inside a walk can hang the child.** A child forked while other threads walk a shared container can inherit that container's lock held, and wait on it for good; the interpreters with a lock take no per-container lock. CPython warns against forking a threaded process in any case; start worker processes with the `spawn` or `forkserver` method.
- **A record's field names are interned for good.** A validator interns the names of the fields it reads, which is what makes a field lookup one pointer comparison, and the free-threaded build makes an interned string immortal: a process that builds a validator per request over field names it has not seen keeps every one of them. The builds with a lock free them with the last validator that held them.
