How to Install Marin on Linux, macOS, and Windows: The Complete Guide

Marin installs identically across all platforms using uv for environment management, requiring only OS-specific build prerequisites for SentencePiece compilation and optional GPU/TPU extras defined in pyproject.toml.

Marin is a Python-first machine learning framework hosted in the marin-community/marin repository that leverages JAX for hardware acceleration and uv for lightning-fast dependency resolution. While the core installation workflow remains consistent across operating systems, each platform requires specific system-level dependencies to compile native extensions and enable GPU or TPU support.

Prerequisites by Operating System

Before cloning the repository, ensure your system meets the base requirements for Python 3.12+ and the build tools needed to compile SentencePiece.

Linux

Linux systems require the most comprehensive build environment to support native compilation:

• Python >= 3.12
• uv (install via pip install uv)
• Git
• Build essentials: build-essential, cmake, pkg-config, coreutils
• (Optional) NVIDIA driver >= 580 and CUDA 13 for GPU support

Install system dependencies on Ubuntu/Debian with:

sudo apt-get update
sudo apt-get install build-essential cmake pkg-config coreutils git

macOS

macOS relies on Homebrew for build dependencies since Xcode command line tools alone are insufficient for SentencePiece compilation:

• Python >= 3.12 and uv
• Xcode Command Line Tools (xcode-select --install)
• Homebrew packages: brew install cmake pkg-config coreutils
• (Optional) Rust toolchain via rustup for building native Rust wheels from source

Note that macOS does not support NVIDIA CUDA. For GPU acceleration, you must use CPU mode locally or connect to a remote Linux GPU cluster.

Windows

Windows requires the fewest additional build packages since pre-built wheels handle most dependencies:

• Python >= 3.12 and uv
• Git for Windows
• (Optional) Rust toolchain via rustup for source builds
• (Optional) CUDA 13 Toolkit for GPU support

Install the CUDA Toolkit separately from NVIDIA’s website before attempting GPU installation.

Core Installation Steps

Clone and Environment Setup

All platforms begin by cloning the repository and creating a virtual environment using uv. According to docs/tutorials/installation.md, the standardized workflow starts with:

git clone https://github.com/marin-community/marin.git && cd marin
uv venv --python 3.12

Activate the environment using OS-specific syntax:

Linux/macOS:

source .venv/bin/activate

Windows:

.venv\Scripts\activate

Installing Core Dependencies

Install the CPU-only base package using the lock file defined in the repository root. The pyproject.toml file organizes dependencies into extras groups, but the base installation requires only:

uv sync --all-packages

This command installs JAX for CPU, all Python dependencies, and pre-built wheels for Rust extensions. For source builds of Rust components, run make rust-dev before syncing to modify pyproject.toml to use path-based dependencies.

Configuring GPU and TPU Support

Hardware acceleration requires platform-specific extras passed to uv sync.

Linux GPU Setup

After installing the NVIDIA driver >= 580 and CUDA 13 toolkit, install the GPU extras defined in pyproject.toml:

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

The --extra=gpu flag pulls JAX CUDA wheels automatically. Verify GPU visibility with JAX before running training scripts.

macOS Limitations

macOS cannot run NVIDIA GPUs locally. Keep the default CPU installation or configure remote TPU access. If using TPU hardware connected to a macOS development machine, install:

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

Windows GPU Setup

Windows GPU support mirrors Linux but requires manual CUDA 13 installation beforehand:

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

Ensure the CUDA binaries are in your system PATH before activating the virtual environment.

TPU Support

TPU configuration is identical across all three operating systems. Install the TPU extras using:

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

This configures JAX for Cloud TPU access using the libtpu library specified in docs/tutorials/local-gpu.md.

Optional: Building Rust Crates from Source

For development or architecture-specific optimizations, build Rust components from source using the Makefile targets:

make rust-dev    # Switches pyproject.toml to source builds

make rust-status # Verifies Cargo availability

This workflow requires the Rust toolchain (cargo and rustc) installed via rustup on all platforms.

Environment Configuration

Configure required environment variables before running experiments. In docs/tutorials/installation.md, the standard practice includes setting storage paths and API keys:

Linux/macOS:

export WANDB_API_KEY=your_key_here
export HF_TOKEN=your_token_here
export MARIN_PREFIX=$HOME/marin_store

Windows:

set WANDB_API_KEY=your_key_here
set HF_TOKEN=your_token_here
set MARIN_PREFIX=%USERPROFILE%\marin_store

Add these to ~/.bashrc, ~/.zshrc, or Windows system environment variables for persistence.

Verification

Test your installation by running the tiny model tutorial included in experiments/tutorials/train_tiny_model.py:

# CPU verification

export MARIN_PREFIX=local_store
uv run python experiments/tutorials/train_tiny_model.py \
  --device cpu --dataset tinystories --version dev --run

For GPU verification, replace --device cpu with --device gpu or --device tpu after installing the corresponding extras. Successful execution confirms that JAX can access your hardware and all dependencies resolve correctly.

Summary

• Unified workflow: All platforms use uv venv --python 3.12 and uv sync --all-packages for base installation
• Linux extras: Requires build-essential and NVIDIA driver >= 580 for GPU support
• macOS constraints: No local CUDA support; install cmake, pkg-config, and coreutils via Homebrew for SentencePiece
• Windows specifics: Use .venv\Scripts\activate and install CUDA 13 separately for GPU extras
• Hardware flags: Append --extra=gpu or --extra=tpu to enable accelerators as defined in pyproject.toml
• Source builds: Use make rust-dev to compile Rust crates from source when pre-built wheels are unavailable

Frequently Asked Questions

Does Marin support Apple Silicon GPUs?

No. As documented in docs/tutorials/installation.md, Marin relies on JAX for hardware acceleration, and JAX does not support the Metal Performance Shaders backend required for Apple Silicon GPUs. MacOS installations should use the default CPU configuration or connect to remote Linux GPU/TPU clusters.

Why does the installation fail with SentencePiece build errors on Linux?

Missing system build tools prevent the SentencePiece Python wrapper from compiling native extensions. Install build-essential, cmake, pkg-config, and coreutils using your distribution’s package manager before running uv sync. These dependencies are listed in the prerequisites table in docs/tutorials/installation.md.

Can I install Marin on Windows without CUDA for CPU-only training?

Yes. Run uv sync --all-packages without the --extra=gpu flag to install CPU-only JAX wheels. Windows requires no additional build tools for CPU operation, though you still need Git and Python 3.12+.

What is the difference between uv sync and pip install for Marin?

Marin explicitly uses uv (Ultra-fast Python package installer) instead of pip for dependency resolution and environment management. The pyproject.toml and lock files in the marin-community/marin repository are optimized for uv’s resolver, and installation via pip may fail to correctly resolve the JAX CUDA/TPU wheel indexes specified in the project configuration.

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