> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nixl/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nixl/_mcp/server.

# Building NIXLBench

> Build NIXLBench using Docker or natively from source with Meson.

NIXLBench requires a NIXL installation -- see [Building NIXL from Source](/nixl/developer-guide/building-nixl-from-source) for instructions.

## System Requirements

### Hardware

- **CPU:** x86_64 or aarch64 architecture
- **Memory:** 8 GB RAM minimum, 16 GB or more recommended for compilation
- **Storage:** 20 GB free disk space
- **GPU:** NVIDIA GPU with CUDA support (for GPU features)
- **Network:** InfiniBand or Ethernet adapters (for network backends)

### Software

- **OS:** Ubuntu 22.04 or 24.04 LTS (recommended), or RHEL-based distributions
- **Docker:** 20.10 or later (for container builds)
- **CUDA Toolkit:** 12.8 or later
- **Python:** 3.12 or later
- **Compiler:** C++20-compatible compiler

## Build Instructions

<Tabs>
<Tab title="Docker">

The Docker build handles all dependencies automatically and is the recommended approach.

Clone the repository and navigate to the build directory:

```bash
git clone https://github.com/ai-dynamo/nixl.git
cd nixl/benchmark/nixlbench/contrib
```

Build the container with default settings:

```bash
./build.sh
```

Common build options:

```bash
# Debug build
./build.sh --build-type debug

# Build for aarch64
./build.sh --arch aarch64

# Combine options
./build.sh --build-type debug --arch aarch64
```

For the full list of build options, see the [NIXLBench README](https://github.com/ai-dynamo/nixl/tree/main/benchmark/nixlbench).

Run a quick benchmark to verify the build:

```bash
docker run -it --gpus all --network host nixlbench:latest \
  nixlbench --backend GDS --filepath /tmp/nixlbench-test
```

</Tab>
<Tab title="Native">

Build NIXLBench natively when Docker is not available or for development workflows. NIXL must be built and installed first -- see [Building NIXL from Source](/nixl/developer-guide/building-nixl-from-source).

### Core Dependencies

- [UCX](/nixl/user-guide/backend-selection/ucx)
- CUDA Toolkit (12.8 or later)
- Meson
- Ninja
- standalone ASIO
- GFlags
- OpenMP
- etcd-cpp-api (required for runs with more than two workers)

### Build Steps

```bash
cd benchmark/nixlbench
meson setup build -Dnixl_path=/usr/local/nixl --buildtype=release
cd build && ninja && sudo ninja install
```

### Meson Build Options

| Option | Description | Default |
|--------|-------------|---------|
| `nixl_path` | Path to NIXL installation | `/usr/local` |
| `buildtype` | Build type: `debug`, `release`, `debugoptimized` | `release` |
| `prefix` | Installation prefix | `/usr/local` |
| `etcd_inc_path` | Path to etcd C++ client headers | `""` |
| `etcd_lib_path` | Path to etcd C++ client library | `""` |

### Post-Install Setup

Add NIXLBench to your environment:

```bash
export PATH=/usr/local/nixlbench/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/nixlbench/lib:$LD_LIBRARY_PATH
```

</Tab>
</Tabs>