Installation

This guide walks you through installing NextStat step by step. By the end you will have a working environment and be able to run your first fit. No prior experience with Rust or statistical inference is required.

Step 0: Prerequisites

Before you begin, make sure you have the following installed on your machine:

If you don't have Python yet:

# macOS (Homebrew)
brew install [email protected]

# Ubuntu / Debian
sudo apt update && sudo apt install python3.12 python3.12-venv python3-pip

# Windows — download from https://python.org/downloads
# During install, check "Add Python to PATH"

Step 1: Install via pip (recommended)

This is the fastest way. Pre-built binary wheels are available for:

• Linux x86_64 and aarch64
• macOS Apple Silicon (arm64)
• macOS Intel (x86_64)
• Windows x86_64

1a. Create a virtual environment (strongly recommended)

A virtual environment keeps NextStat and its dependencies isolated from your system Python.

# Create a new virtual environment called "ns-env"
python3 -m venv ns-env

# Activate it
# macOS / Linux:
source ns-env/bin/activate
# Windows (PowerShell):
ns-env\Scripts\Activate.ps1
# Windows (cmd):
ns-env\Scripts\activate.bat

# Your prompt should now show (ns-env) at the beginning

1b. Install the package

pip install nextstat

This downloads a pre-compiled wheel (~15 MB) and installs it. No Rust compiler needed.

1c. Verify the installation

python3 -c "import nextstat; print(nextstat.__version__)"

Expected output:

0.9.5

1d. Install optional extras

NextStat has optional dependency groups for specific features:

Alternative: Install as a Rust crate

If you are building a Rust application and want to use NextStat as a library:

# Make sure you have Rust 1.93+
rustup update stable
rustc --version   # should print 1.93.0 or higher

# Add NextStat crates to your project
cargo add ns-core ns-inference ns-compute

Then in your main.rs or lib.rs:

use ns_inference::mle::MaximumLikelihoodEstimator;
// You're ready to go!

Alternative: Build from source

Only needed if you want to modify NextStat itself, or if no pre-built wheel exists for your platform.

Requirements

Step-by-step

# 1. Clone the repository
git clone https://github.com/NextStat/nextstat.io.git
cd nextstat.io

# 2. Build the entire Rust workspace (takes 2-5 minutes on first build)
cargo build --release

# 3. Create a virtual environment for Python
python3 -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows

# 4. Install maturin (the Rust-Python build tool)
pip install maturin

# 5. Build and install the Python bindings in development mode
cd bindings/ns-py
maturin develop --release

# 6. Verify
python3 -c "import nextstat; print(nextstat.__version__)"
# Expected: 0.9.4

GPU Acceleration (optional)

NextStat supports GPU-accelerated toy fitting and batch NLL evaluation. This is optional — everything works on CPU by default.

# Build from source with CUDA support
cargo build --workspace --features cuda

# Build from source with Metal support (Apple Silicon)
cargo build --workspace --features metal

Troubleshooting

"No matching distribution found"

This means there is no pre-built wheel for your platform. Check your Python version (python3 --version) — you need 3.11 or higher. If you are on an unusual architecture, build from source (see above).

"pip: command not found"

Try pip3 instead of pip. On some systems, pip is only available inside a virtual environment. Create one first (Step 1a above).

"error: linker 'cc' not found" (building from source)

You need a C compiler. Install build tools:

# macOS
xcode-select --install

# Ubuntu / Debian
sudo apt install build-essential

# Fedora
sudo dnf install gcc

Next Steps

Now that NextStat is installed, head to the Quickstart guide to run your first fit in under 5 minutes.