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

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.

Clone the Repository

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

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, which declares the project dependencies and optional extras.

Set Up the Python Environment

Headroom uses a modern 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.

# 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:

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

The 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. The Python side loads the compiled shared library via maturin.

First, install the Rust toolchain:

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

Then build the native extension in editable mode:

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:

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:

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

Inside the container, run the same setup commands:

uv sync --extra dev
uv run pytest

This approach is useful for CI pipelines—validated by 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 and 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}