# How to Build Marin from Source: Complete Installation Guide

> Build Marin from source with this complete installation guide. Follow steps to clone, set up your environment, install dependencies, and configure variables for a successful build.

- Repository: [The Marin Project/marin](https://github.com/marin-community/marin)
- Tags: getting-started
- Published: 2026-08-27

---

**To build Marin from source, clone the repository, create a Python 3.12+ virtual environment using `uv`, install dependencies with `uv sync --all-packages` and the appropriate hardware extra (`cpu`, `gpu`, or `tpu`), optionally compile Rust extensions via `make rust-dev`, and configure the required environment variables before running the tutorial script.**

Marin is a modular research platform designed for training large language models at scale. Its architecture comprises several specialized layers—from the JAX-based **Levanter** training library to the **Iris** job orchestration system and **Zephyr** data processing layer. Building Marin from source allows you to modify these core components and run experiments on CPUs, GPUs, or TPUs according to the procedures documented in [`docs/tutorials/installation.md`](https://github.com/marin-community/marin/blob/main/docs/tutorials/installation.md).

## Prerequisites for Building Marin

Before compiling, ensure your system meets the baseline requirements. Marin requires **Python 3.12 or newer**, the **`uv` package manager** for dependency resolution, and **Git** for source control. While optional, a **Rust toolchain** is necessary if you intend to build native extensions from source rather than using pre-compiled wheels.

## Step-by-Step Build Instructions

### 1. Clone the Repository

Fetch the latest source code from the marin-community organization:

```bash
git clone https://github.com/marin-community/marin.git
cd marin

```

### 2. Create a Python 3.12 Virtual Environment

Marin development relies on `uv` for environment management. Create and activate an isolated environment:

```bash
uv venv --python 3.12
source .venv/bin/activate

# Windows users: .venv\Scripts\activate

```

### 3. Install Core Dependencies with Hardware Extras

Install the full package stack in editable mode. You must specify the hardware target to pull the correct JAX wheels as declared in [`pyproject.toml`](https://github.com/marin-community/marin/blob/main/pyproject.toml):

```bash

# CPU-only installation

uv sync --all-packages

# For GPU support

uv sync --all-packages --extra=gpu

# For TPU support

uv sync --all-packages --extra=tpu

```

### 4. Build Rust Extensions from Source (Optional)

If you need to modify native code, switch from pre-built wheels to local Cargo builds using the Makefile targets:

```bash
make rust-dev
uv sync --all-packages

```

The `make rust-dev` target modifies [`pyproject.toml`](https://github.com/marin-community/marin/blob/main/pyproject.toml) to reference local Cargo builds. To revert to standard wheels after development, run `make rust-user`.

### 5. Configure Environment Variables

Marin requires three critical environment variables for operation. Set these before running experiments:

```bash
export WANDB_API_KEY=your_key
export HF_TOKEN=your_hf_token
export MARIN_PREFIX=$HOME/marin_artifacts

```

The `MARIN_PREFIX` variable specifies an fsspec-compatible path for artifact storage, while `WANDB_API_KEY` and `HF_TOKEN` enable experiment tracking and gated model access via the Hugging Face Hub.

### 6. Verify the Build with the Tutorial

Run the tiny-model tutorial to confirm your installation succeeds:

```bash
wandb offline
uv run python experiments/tutorials/train_tiny_model.py \
  --device cpu \
  --dataset tinystories \
  --version dev \
  --run

```

This executes the minimal pipeline defined in [`experiments/tutorials/train_tiny_model.py`](https://github.com/marin-community/marin/blob/main/experiments/tutorials/train_tiny_model.py), validating that Levanter, Iris, Zephyr, and the Marin orchestration layer are functioning correctly.

## Understanding Marin’s Modular Architecture

Building from source requires awareness of how Marin’s components interact. The repository organizes functionality into distinct layers documented in their respective README files:

- **`lib/levanter/`** – Contains the JAX-based training library providing model components, optimizers, and data pipelines. Reference [`lib/levanter/README.md`](https://github.com/marin-community/marin/blob/main/lib/levanter/README.md) for low-level APIs.

- **`lib/iris/`** – Implements job orchestration that abstracts cluster resources and manages automatic retries across CPUs, GPUs, and TPUs. See [`lib/iris/README.md`](https://github.com/marin-community/marin/blob/main/lib/iris/README.md) for scheduling documentation.

- **`lib/zephyr/`** – Provides dataset processing utilities including readers, writers, and the "vortex" in-memory abstraction for streaming large datasets. Consult [`lib/zephyr/README.md`](https://github.com/marin-community/marin/blob/main/lib/zephyr/README.md) for data pipeline configurations.

- **`lib/marin/`** – The top-level pipeline framework that composes training steps as a DAG and manages lazy artifact materialization, integrating with Weights & Biases for experiment tracking.

## Key Configuration Files

Several repository files govern the build process and validation:

- **[`docs/tutorials/installation.md`](https://github.com/marin-community/marin/blob/main/docs/tutorials/installation.md)** – The authoritative source for installation procedures and troubleshooting.

- **[`pyproject.toml`](https://github.com/marin-community/marin/blob/main/pyproject.toml)** – Declares Python dependencies, optional JAX extras for hardware acceleration, and Rust extension metadata.

- **`Makefile`** – Provides the `rust-dev` and `rust-user` targets for switching between source and wheel-based native extensions.

- **[`experiments/tutorials/train_tiny_model.py`](https://github.com/marin-community/marin/blob/main/experiments/tutorials/train_tiny_model.py)** – The canonical verification script that exercises the full stack.

- **[`tests/vllm/test_llm_inference.py`](https://github.com/marin-community/marin/blob/main/tests/vllm/test_llm_inference.py)** – Example unit test for validating VLLM integration.

- **[`.github/workflows/marin-lint.yaml`](https://github.com/marin-community/marin/blob/main/.github/workflows/marin-lint.yaml)** – CI workflow demonstrating the exact steps used to validate successful builds in continuous integration.

## Summary

Building Marin from source establishes a development environment matching the core maintainers' configuration. Key steps include:

- Cloning the repository and initializing a Python 3.12 virtual environment with `uv`
- Installing dependencies via `uv sync` with hardware-specific extras (`--extra=cpu`, `gpu`, or `tpu`)
- Optionally compiling Rust extensions using `make rust-dev` when modifying native code
- Configuring `WANDB_API_KEY`, `HF_TOKEN`, and `MARIN_PREFIX` environment variables
- Validating the build by executing [`experiments/tutorials/train_tiny_model.py`](https://github.com/marin-community/marin/blob/main/experiments/tutorials/train_tiny_model.py)

## Frequently Asked Questions

### What Python version is required to build Marin?

Marin requires **Python 3.12 or newer**. Earlier versions are not supported due to dependency constraints in the JAX ecosystem and type annotation features used throughout `lib/levanter/` and `lib/marin/`.

### Do I need to install Rust to build Marin from source?

**No**, Rust is only required if you intend to modify or debug the native extensions. By default, `uv sync` installs pre-compiled wheels. Use `make rust-dev` only when you need to compile the Rust crates from source using Cargo, as configured in [`pyproject.toml`](https://github.com/marin-community/marin/blob/main/pyproject.toml).

### How do I switch between CPU and GPU builds after initial installation?

Re-run `uv sync --all-packages` with the appropriate extra flag. For example, switch to GPU by executing `uv sync --all-packages --extra=gpu`, which updates the JAX installation in your virtual environment to use CUDA-enabled wheels defined in [`pyproject.toml`](https://github.com/marin-community/marin/blob/main/pyproject.toml).

### Where does Marin store built artifacts and model checkpoints?

The `MARIN_PREFIX` environment variable controls artifact storage. Set this to any fsspec-compatible path (local filesystem or cloud storage URI). By default, the tutorial suggests `$HOME/marin_artifacts`, but production deployments typically use distributed storage paths for scalability.