# How to Set Up a Local Development Environment for Marin

> Set up your local development environment for Marin quickly. Learn to install Python, uv, Git, clone the repo, and configure dependencies for seamless Marin development.

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

---

**Setting up a local development environment for Marin requires Python 3.12+, the uv package manager, and Git, followed by cloning the repository, creating a virtual environment, installing hardware-specific dependencies with `uv sync`, and configuring optional environment variables for Weights & Biases and Hugging Face.**

Marin is an open-source machine learning framework maintained by the **marin-community** organization. Setting up a local development environment for Marin involves using modern Python tooling to manage dependencies and hardware-specific JAX builds for CPU, GPU, or TPU acceleration. This guide walks through the complete installation process based on the canonical documentation in [`docs/tutorials/installation.md`](https://github.com/marin-community/marin/blob/main/docs/tutorials/installation.md).

## Prerequisites

Before installing Marin, ensure your system meets the baseline requirements. You will need **Python 3.12+**, the **uv** package manager, and **Git**. macOS users may need additional build tools for SentencePiece compilation. Optionally, install the **Rust toolchain** if you plan to build native crates from source instead of using pre-built wheels.

## Clone the Marin Repository

Start by cloning the repository from GitHub. This downloads the source code, configuration files defined in [`config/marin.yaml`](https://github.com/marin-community/marin/blob/main/config/marin.yaml), and tutorial scripts to your local machine.

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

```

## Create and Activate a Virtual Environment

Marin uses `uv` to manage Python environments and dependencies. Create an isolated virtual environment specifying Python 3.12, then activate it.

```bash
uv venv --python 3.12
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

```

## Install Marin with Hardware-Specific Dependencies

The installation command varies based on your hardware acceleration needs. Marin defines hardware-specific extras in [`pyproject.toml`](https://github.com/marin-community/marin/blob/main/pyproject.toml) to install the correct JAX build for your system.

### CPU Installation

For development on machines without dedicated accelerators, install the CPU variant:

```bash
uv sync --all-packages --extra=cpu

```

### GPU Installation

For NVIDIA GPU support, first install **CUDA 12.9** and **cuDNN** according to the official documentation. Then install Marin with the GPU extra:

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

```

### TPU Installation

For Google Cloud TPU environments, use the TPU-specific extra:

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

```

The `uv sync` command resolves all Python dependencies listed in [`pyproject.toml`](https://github.com/marin-community/marin/blob/main/pyproject.toml) and installs the local package in editable mode, making the process take approximately 5–10 minutes due to source builds of some dependencies.

## Configure Environment Variables

Marin relies on several environment variables for optional integrations and artifact storage. Create a `.env` file in the project root to store these values.

Set `MARIN_PREFIX` to define where checkpoints, datasets, and other artifacts are written. This path supports local directories or fsspec-compatible storage like GCS buckets.

Configure **Weights & Biases** for experiment tracking by setting `WANDB_API_KEY`, and optionally `WANDB_ENTITY` and `WANDB_PROJECT`. For accessing gated models on **Hugging Face**, set `HF_TOKEN`.

Example `.env` file:

```bash
export MARIN_PREFIX="$HOME/marin_store"
export WANDB_API_KEY="your-wandb-key"
export HF_TOKEN="your-huggingface-token"

```

Source the file to apply variables:

```bash
source .env

```

## Optional: Build Rust Crates from Source

By default, Marin pulls pre-built native Rust wheels from PyPI. To compile the Rust crates from source instead, use the **Makefile** targets provided in the repository root.

```bash
make rust-dev   # For development builds

make rust-user  # For optimized user builds

```

This step requires the Rust toolchain to be installed and available in your PATH.

## Verify Your Installation

Confirm your local development environment works by running the First Experiment tutorial. This script trains a tiny language model on the TinyStories dataset using only CPU resources.

First, optionally disable Weights & Biases logging:

```bash
wandb offline

```

Then execute the verification script located at [`experiments/tutorials/train_tiny_model.py`](https://github.com/marin-community/marin/blob/main/experiments/tutorials/train_tiny_model.py):

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

```

This command tokenizes the dataset, trains a small model, and writes checkpoints to the location defined by `MARIN_PREFIX`. Successful completion confirms that the setup outlined in [`docs/tutorials/installation.md`](https://github.com/marin-community/marin/blob/main/docs/tutorials/installation.md) is functioning correctly.

## Summary

- Install **Python 3.12+**, **uv**, and **Git** before starting, with optional Rust tools for building native crates.
- Clone the **marin-community/marin** repository and create a virtual environment with `uv venv --python 3.12`.
- Use `uv sync --all-packages --extra={cpu|gpu|tpu}` to install hardware-specific dependencies defined in [`pyproject.toml`](https://github.com/marin-community/marin/blob/main/pyproject.toml).
- Configure `MARIN_PREFIX`, `WANDB_API_KEY`, and `HF_TOKEN` in a `.env` file for artifact storage and optional integrations.
- Run [`experiments/tutorials/train_tiny_model.py`](https://github.com/marin-community/marin/blob/main/experiments/tutorials/train_tiny_model.py) to verify the installation trains a model successfully.

## Frequently Asked Questions

### What Python version is required for Marin?

Marin requires **Python 3.12 or newer**. The installation process explicitly uses `uv venv --python 3.12` to ensure compatibility with the dependency specifications in [`pyproject.toml`](https://github.com/marin-community/marin/blob/main/pyproject.toml).

### Do I need a GPU to run Marin locally?

No. Marin supports CPU-only development using the `--extra=cpu` flag during installation. The verification tutorial in [`experiments/tutorials/train_tiny_model.py`](https://github.com/marin-community/marin/blob/main/experiments/tutorials/train_tiny_model.py) runs entirely on CPU, making it accessible for development on laptops or workstations without dedicated accelerators.

### How do I switch between CPU and GPU installations?

Re-run the installation command with the appropriate extra flag. For GPU support, first install CUDA 12.9 and cuDNN, then execute `uv sync --all-packages --extra=gpu`. To revert to CPU-only, use `uv sync --all-packages --extra=cpu`. The `uv` tool automatically manages the different JAX builds specified in [`pyproject.toml`](https://github.com/marin-community/marin/blob/main/pyproject.toml).

### Where does Marin store checkpoints and datasets?

Marin writes artifacts to the path defined by the `MARIN_PREFIX` environment variable. According to [`docs/tutorials/installation.md`](https://github.com/marin-community/marin/blob/main/docs/tutorials/installation.md), this variable points to a local directory or an fsspec-compatible remote storage location such as a Google Cloud Storage bucket. All checkpoints, datasets, and experimental outputs are organized under this prefix.