# How to Install Headroom from Source Code: A Complete Build Guide

> Install Headroom from source code with this complete build guide. Learn to clone the repository, set up your environment, and build the native extension efficiently.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-21

---

**To install Headroom from source, clone the `chopratejas/headroom` repository, set up a Python 3.10+ environment with `uv` or `pip`, install the Rust toolchain, and build the native extension using `maturin`.**

Headroom is a pure‑Python package with a small Rust component that provides token‑compression for AI agents. Installing it from source lets you work on the latest code, customize the build, or run the test suite locally. This guide walks through the complete build process using the actual source files found in the repository.

## Prerequisites

Before cloning, ensure your system meets the baseline requirements. Headroom requires **Python 3.10 or newer** and a functional **Rust toolchain** to compile the native compression engine located in `headroom/_native/`.

You will also need a Python environment manager. The project recommends **uv**, a fast Python package manager written in Rust, though standard `pip` workflows are fully supported as documented in [`CONTRIBUTING.md`](https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md).

## Clone the Repository

Start by cloning the public GitHub repository and navigating into the source tree.

```bash
git clone https://github.com/chopratejas/headroom.git
cd headroom

```

The top‑level layout contains the Python package under the **`headroom/`** directory and the build metadata in **[`pyproject.toml`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml)**, which declares the project dependencies and optional extras.

## Set Up the Python Environment

Headroom uses a modern [`pyproject.toml`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml) layout and declares optional extras for development (`dev`), ML models (`ml`), and proxy functionality (`proxy`).

### Using uv (Recommended)

The **`uv`** tool resolves dependencies and creates an isolated virtual environment automatically.

```bash

# Install uv if you don't have it

curl -LsSf https://raw.github.com/astral-sh/uv/master/install.sh | sh

# Create an isolated env and install all development extras

uv sync --extra dev
uv run pytest

```

### Using pip (Alternative)

If you prefer `pip`, create a virtual environment manually and install in editable mode with the development extras:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

```

The [`pyproject.toml`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml) file maps these extras to the `headroom-ai[all]` distribution, pulling in the ML model, proxy server, and MCP tools when specified.

## Build the Rust Extension Module

Headroom’s compression engine lives in the **`headroom/_native/`** crate, defined in **[`Cargo.toml`](https://github.com/chopratejas/headroom/blob/main/Cargo.toml)**. The Python side loads the compiled shared library via **maturin**.

First, install the Rust toolchain:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable

```

Then build the native extension in editable mode:

```bash
uv run maturin develop

```

If you are using `pip`, the command `pip install -e ".[all]"` will invoke `maturin` automatically to compile the Rust sources. For corporate networks with SSL inspection, pre‑install the Rust toolchain and set `REQUESTS_CA_BUNDLE` before running the install command.

## Verify the Installation

Confirm the build succeeded by checking the CLI version and running the test suite:

```bash
headroom --version          # should report the local git commit hash

headroom perf               # runs a quick sanity check and prints token savings

pytest -q                   # runs the full test suite (≈200 tests)

```

When `headroom perf` executes without errors, you have a functioning proxy, library, and optional ML model. The output should display compression rates similar to the ≈90% token reduction advertised in the project documentation.

## Docker-Based Development (Optional)

For an isolated container workflow, build the image from the **`Dockerfile`**:

```bash
docker build -t headroom-dev .
docker run -it --rm headroom-dev bash

```

Inside the container, run the same setup commands:

```bash
uv sync --extra dev
uv run pytest

```

This approach is useful for CI pipelines—validated by [`scripts/validate-workflows.sh`](https://github.com/chopratejas/headroom/blob/main/scripts/validate-workflows.sh)—or when avoiding Rust installation on your host machine.

## Summary

- Headroom requires Python 3.10+, a Rust toolchain (`rustup`), and either `uv` or `pip` to install from source.
- Clone the repository from `chopratejas/headroom` and navigate to the directory containing [`pyproject.toml`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml) and [`Cargo.toml`](https://github.com/chopratejas/headroom/blob/main/Cargo.toml).
- Install development extras using `uv sync --extra dev` or `pip install -e ".[dev]"`.
- Compile the Rust extension with `maturin develop` or let `pip` invoke it automatically during the editable install.
- Verify with `headroom perf` and `pytest` to ensure the compression engine and test suite function correctly.

## Frequently Asked Questions

### What is the minimum Python version required to install Headroom from source?

Headroom requires **Python 3.10 or newer** according to the `project.requires-python` field in [`pyproject.toml`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml). Earlier versions are not supported due to modern typing and asyncio features used in the codebase.

### Why does Headroom require a Rust toolchain for source installation?

The core compression engine is written in Rust and located in the `headroom/_native/` crate. The `maturin` build tool compiles this Rust code into a Python extension module that the `headroom` package imports at runtime. Without `rustup` and a stable Rust compiler, the editable install will fail when attempting to build the native shared library.

### Can I install Headroom from source without installing Rust on my machine?

Yes, you can use the provided **Dockerfile** to build a containerized environment that includes the Rust toolchain. Run `docker build -t headroom-dev .` and execute your development commands inside the container, avoiding the need to install Rust directly on your host operating system.

### What are the `[dev]` extras in the pyproject.toml file?

The **`[project.optional-dependencies]`** section in [`pyproject.toml`](https://github.com/chopratejas/headroom/blob/main/pyproject.toml) defines extra dependency groups. The `dev` extra includes testing frameworks like `pytest`, linting tools, and other development utilities required to run the full test suite and validate workflows using [`scripts/validate-workflows.sh`](https://github.com/chopratejas/headroom/blob/main/scripts/validate-workflows.sh).