> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/onnxruntime-genai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build from Source

> Build ONNX Runtime GenAI from source for development or custom configurations

This guide covers building ONNX Runtime GenAI from source on Linux, Windows, and macOS.

## Prerequisites

### Common Requirements

<CardGroup cols={2}>
  <Card title="CMake" icon="gear">
    Version 3.26 or higher (3.28+ for macOS xcframework support)
  </Card>

  <Card title="Python" icon="python">
    Python 3.8 or higher
  </Card>

  <Card title="Git" icon="git">
    For cloning the repository
  </Card>

  <Card title="C++ Compiler" icon="code">
    GCC 11+, Clang, or MSVC
  </Card>
</CardGroup>

### Platform-Specific Requirements

<Tabs>
  <Tab title="Linux">
    ```bash theme={null}
    # Ubuntu/Debian
    sudo apt-get update
    sudo apt-get install build-essential cmake git python3 python3-pip

    # GCC 11 or higher required
    gcc --version  # Should be >= 11.0
    ```
  </Tab>

  <Tab title="Windows">
    * Visual Studio 2022 (17.0 or higher)
    * Windows SDK 10.0 or higher
    * CMake 3.26+
    * Python 3.8+

    Install Visual Studio with:

    * Desktop development with C++
    * Windows SDK
    * CMake tools
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    # Install Xcode Command Line Tools
    xcode-select --install

    # Install Homebrew (if not already installed)
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    # Install dependencies
    brew install cmake python@3.11 git
    ```
  </Tab>
</Tabs>

### Optional: Hardware Acceleration

<AccordionGroup>
  <Accordion title="CUDA Support">
    For NVIDIA GPU acceleration:

    * CUDA Toolkit 11.8 or higher
    * cuDNN compatible with your CUDA version
    * Set `CUDA_HOME` or `CUDA_PATH` environment variable

    ```bash theme={null}
    export CUDA_HOME=/usr/local/cuda
    export PATH=$CUDA_HOME/bin:$PATH
    ```
  </Accordion>

  <Accordion title="ROCm Support">
    For AMD GPU acceleration:

    * ROCm 5.0 or higher
    * Compatible AMD GPU
  </Accordion>

  <Accordion title="DirectML Support (Windows)">
    For Windows DirectML acceleration:

    * Windows 10/11
    * DirectX 12 capable GPU
    * No additional installation required
  </Accordion>
</AccordionGroup>

## Clone the Repository

```bash theme={null}
git clone https://github.com/microsoft/onnxruntime-genai.git
cd onnxruntime-genai
```

## Build Phases

The build system supports three phases:

1. **Update** (`--update`): Run CMake to generate makefiles
2. **Build** (`--build`): Build all projects
3. **Test** (`--test`): Run all unit tests

<Note>
  **Default behavior:**

  * Native builds: `--update --build --test`
  * Cross-compiled builds: `--update --build` (tests skipped)
</Note>

## Basic Build

### CPU-Only Build

<CodeGroup>
  ```bash Linux/macOS theme={null}
  python build.py --config Release
  ```

  ```cmd Windows theme={null}
  python build.py --config Release
  ```
</CodeGroup>

This will:

* Generate build files in `build/<platform>/Release`
* Build the C++ library
* Build the Python wheel
* Run tests (unless `--skip_tests` is specified)

### Build with CUDA

```bash theme={null}
python build.py --config Release --use_cuda --cuda_home /usr/local/cuda
```

<Info>
  If `CUDA_HOME` or `CUDA_PATH` environment variable is set, you can omit `--cuda_home`.
</Info>

### Build with DirectML (Windows)

```cmd theme={null}
python build.py --config Release --use_dml
```

### Build with ROCm

```bash theme={null}
python build.py --config Release --use_rocm
```

## Build Options

### Configuration

<ParamField path="--config" type="string" default="RelWithDebInfo">
  Build configuration: `Debug`, `Release`, `RelWithDebInfo`, or `MinSizeRel`
</ParamField>

<ParamField path="--build_dir" type="path">
  Custom build directory (default: `build/<platform>/<config>`)
</ParamField>

### Build Phases

<ParamField path="--update" type="flag">
  Run CMake to generate/update makefiles
</ParamField>

<ParamField path="--build" type="flag">
  Build the project
</ParamField>

<ParamField path="--test" type="flag">
  Run tests after building
</ParamField>

<ParamField path="--clean" type="flag">
  Clean build artifacts for the selected configuration
</ParamField>

<ParamField path="--package" type="flag">
  Package the build output
</ParamField>

### Hardware Acceleration

<ParamField path="--use_cuda" type="flag">
  Enable CUDA support
</ParamField>

<ParamField path="--cuda_home" type="path">
  Path to CUDA installation (default: `$CUDA_HOME` or `$CUDA_PATH`)
</ParamField>

<ParamField path="--use_rocm" type="flag">
  Enable ROCm support for AMD GPUs
</ParamField>

<ParamField path="--use_dml" type="flag">
  Enable DirectML support (Windows only)
</ParamField>

<ParamField path="--use_trt_rtx" type="flag">
  Enable TensorRT-RTX support
</ParamField>

### Language Bindings

<ParamField path="--build_csharp" type="flag">
  Build C# API bindings
</ParamField>

<ParamField path="--build_java" type="flag">
  Build Java bindings
</ParamField>

<ParamField path="--skip_wheel" type="flag">
  Skip building the Python wheel
</ParamField>

### Other Options

<ParamField path="--parallel" type="flag">
  Enable parallel build
</ParamField>

<ParamField path="--skip_tests" type="flag">
  Skip running tests
</ParamField>

<ParamField path="--skip_examples" type="flag">
  Skip building examples
</ParamField>

<ParamField path="--use_guidance" type="flag">
  Enable guidance support for constrained decoding
</ParamField>

<ParamField path="--cmake_generator" type="string">
  CMake generator (default: "Visual Studio 17 2022" on Windows, "Unix Makefiles" elsewhere)
</ParamField>

<ParamField path="--cmake_extra_defines" type="list">
  Extra CMake definitions (without -D prefix)
</ParamField>

## Advanced Build Scenarios

### Cross-Compilation for Android

```bash theme={null}
python build.py \
  --android \
  --android_abi arm64-v8a \
  --android_api 27 \
  --android_home $ANDROID_HOME \
  --android_ndk_path $ANDROID_NDK_HOME \
  --config Release
```

<ParamField path="--android_abi" type="string" default="arm64-v8a">
  Android ABI: `armeabi-v7a`, `arm64-v8a`, `x86`, or `x86_64`
</ParamField>

<ParamField path="--android_api" type="integer" default="27">
  Android API Level (27 = Android 8.1)
</ParamField>

### Cross-Compilation for iOS

```bash theme={null}
python build.py \
  --ios \
  --apple_sysroot iphoneos \
  --osx_arch arm64 \
  --apple_deploy_target 14.0 \
  --config Release
```

<ParamField path="--ios" type="flag">
  Build for iOS
</ParamField>

<ParamField path="--apple_sysroot" type="string">
  macOS platform SDK location
</ParamField>

<ParamField path="--osx_arch" type="string">
  Target architecture for iOS/macOS
</ParamField>

<ParamField path="--apple_deploy_target" type="string">
  Minimum target platform version
</ParamField>

### Build Apple Framework

```bash theme={null}
python build.py \
  --build_apple_framework \
  --config Release
```

### Windows ARM64

```cmd theme={null}
python build.py --config Release --arm64
```

### Custom ONNX Runtime

Use a custom ONNX Runtime build:

```bash theme={null}
python build.py \
  --config Release \
  --ort_home /path/to/onnxruntime/build
```

## Build Examples

### Development Build with Tests

```bash theme={null}
python build.py \
  --config Debug \
  --parallel \
  --cmake_generator Ninja
```

### Production Build with CUDA

```bash theme={null}
python build.py \
  --config Release \
  --use_cuda \
  --parallel \
  --package
```

### Build Only (Skip Update and Test)

```bash theme={null}
python build.py --build --skip_tests
```

### Clean and Rebuild

```bash theme={null}
python build.py --clean --update --build
```

### Build with Constrained Decoding Support

```bash theme={null}
python build.py \
  --config Release \
  --use_guidance \
  --use_cuda
```

## Installing the Python Package

After building, install the Python wheel:

<CodeGroup>
  ```bash Linux/macOS theme={null}
  pip install build/Linux/Release/dist/*.whl
  ```

  ```cmd Windows theme={null}
  pip install build\Windows\Release\wheel\*.whl
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="CMake Generation Fails">
    * Ensure CMake version is 3.26 or higher (3.28+ for macOS)
    * Check that all dependencies are installed
    * Delete `CMakeCache.txt` and the build directory, then retry
    * Verify compiler version (GCC 11+ required)
  </Accordion>

  <Accordion title="CUDA Not Found">
    * Set `CUDA_HOME` or `CUDA_PATH` environment variable
    * Ensure `nvcc` is in your PATH
    * Verify CUDA Toolkit version is 11.8 or higher

    ```bash theme={null}
    export CUDA_HOME=/usr/local/cuda
    export PATH=$CUDA_HOME/bin:$PATH
    nvcc --version
    ```
  </Accordion>

  <Accordion title="Build Errors on Windows">
    * Ensure Visual Studio 2022 is installed
    * Run build from "Developer Command Prompt for VS 2022"
    * Check that Windows SDK is installed
    * Try specifying generator explicitly: `--cmake_generator "Visual Studio 17 2022"`
  </Accordion>

  <Accordion title="Out of Memory During Build">
    * Reduce parallel builds: Remove `--parallel` flag
    * Use `Release` or `MinSizeRel` configuration instead of `Debug`
    * Close other applications
    * Increase system swap/page file
  </Accordion>

  <Accordion title="Test Failures">
    * Ensure model files are accessible
    * Check hardware acceleration is properly configured
    * Try running tests individually to isolate issues
    * Use `--skip_tests` to skip testing during build
  </Accordion>
</AccordionGroup>

## Build System Details

### Build Directory Structure

```
onnxruntime-genai/
├── build/
│   ├── Linux/
│   │   ├── Debug/
│   │   └── Release/
│   ├── Windows/
│   │   ├── Debug/
│   │   └── Release/
│   └── macOS/
│       ├── Debug/
│       └── Release/
├── src/
├── test/
├── examples/
└── build.py
```

### CMake Variables

You can pass custom CMake variables:

```bash theme={null}
python build.py \
  --cmake_extra_defines \
    CMAKE_INSTALL_PREFIX=/custom/path \
    BUILD_SHARED_LIBS=ON
```

### Environment Variables

<ParamField path="CUDA_HOME" type="path">
  Path to CUDA installation
</ParamField>

<ParamField path="CUDA_PATH" type="path">
  Alternative path to CUDA (Windows)
</ParamField>

<ParamField path="ANDROID_HOME" type="path">
  Path to Android SDK
</ParamField>

<ParamField path="ANDROID_NDK_HOME" type="path">
  Path to Android NDK
</ParamField>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Run your first inference with the built package
  </Card>

  <Card title="Model Builder" icon="hammer" href="/guides/model-builder">
    Build optimized ONNX models
  </Card>

  <Card title="Contributing" icon="code-pull-request" href="https://github.com/microsoft/onnxruntime-genai/blob/main/CONTRIBUTING.md">
    Contribute to ONNX Runtime GenAI
  </Card>

  <Card title="Examples" icon="flask" href="https://github.com/microsoft/onnxruntime-genai/tree/main/examples">
    Explore code examples
  </Card>
</CardGroup>