# Switchyard Requirements: Rust Toolchain, Python Version, and System Prerequisites

> Discover Switchyard requirements: Rust 1.96.1, Python 3.10+, and essential system tools like gcc and git are needed to get started. Optimize your setup now.

- Repository: [NVIDIA-NeMo/Switchyard](https://github.com/NVIDIA-NeMo/Switchyard)
- Tags: getting-started
- Published: 2026-08-21

---

**To run Switchyard, you need Rust 1.96.1, Python 3.10 or higher, and standard system build tools including gcc, make, curl, and git.**

Switchyard is a **Rust-centric** routing engine with a thin Python integration layer maintained in the NVIDIA-NeMo/Switchyard repository. The project enforces strict version pinning to ensure reproducible builds across its core algorithm crates, stand-alone server, and PyO3-based Python façade.

## Core Switchyard Requirements

### Rust Toolchain Version 1.96.1

The repository pins the exact Rust compiler version in [`rust-toolchain.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/rust-toolchain.toml). All crates in the workspace inherit `rust-version = "1.96"` via `rust-version.workspace = true` declarations in their respective [`Cargo.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/Cargo.toml) files.

You must install the specific channel to compile any component, including `switchyard-libsy`, `switchyard-protocol`, and `switchyard-server`. Using `rustup` ensures you match the exact bytecode generation and dependency resolution tested in CI.

```bash

# Install the exact required toolchain

rustup toolchain install 1.96.1
rustup default 1.96.1

# Verify installation

rustc --version  # Expected: 1.96.1

```

### Python Runtime 3.10 or Higher

Although Switchyard’s performance-critical logic is native Rust, the optional Python bindings require CPython 3.10+. This is declared in [`pyproject.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/pyproject.toml) under `requires-python = ">=3.10"`.

The `switchyard_rust` package uses PyO3 to expose the compiled library to Python. When importing the module, Python loads the native binary built by the Rust toolchain specified above.

```bash
python --version  # Must print 3.10.x or higher

```

### System Build Tools

You need a standard Unix-like build environment to compile Rust and its native dependencies. According to [`docs/getting_started.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/getting_started.md), the prerequisites include:

- **Git** for cloning the repository
- **gcc** or **clang** for linking native code
- **make** and **curl** for auxiliary build steps
- `pkg-config` (on Linux) for locating system libraries

These tools compile the `aws-lc-rs` cryptographic primitives and `rustls` TLS stack required by the server crate.

## Optional but Recommended Dependencies

### uv for Python Environment Management

While optional, the maintainers recommend installing `uv` to manage Python virtual environments and run repository tooling. The Getting Started guide explicitly mentions `uv` for linting and CI consistency.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version

```

### TLS Libraries for Secure Connections

The stand-alone server (`switchyard-server`) declared in [`crates/switchyard-server/Cargo.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/Cargo.toml) links against `rustls` and `aws-lc-rs` for HTTPS support. These Rust crates bundle their own cryptographic implementations, but they require system OpenSSL headers only if you enable specific legacy features. For most deployments, the standard system TLS libraries suffice.

## Architecture and Crate Structure

Understanding the dependency flow clarifies why the version requirements are strict:

- **Core libraries**: `switchyard-libsy`, `switchyard-protocol`, and `switchyard-translation` contain the routing algorithms. They all reference the workspace Rust version.
- **Server binary**: `switchyard-server` is a native executable using `axum` and `axum-server` for async HTTP handling. It depends on the core libraries and inherits the same compiler constraints.
- **Python bindings**: [`crates/switchyard-py/Cargo.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-py/Cargo.toml) defines the PyO3 bridge. The resulting wheel contains a shared library compiled against Rust 1.96.1, which Python loads at runtime.

Because the workspace uses a shared [`rust-toolchain.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/rust-toolchain.toml), any deviation from the pinned 1.96.1 channel risks compilation failures in dependencies like `aws-lc-rs`.

## Step-by-Step Installation Guide

### Installing the Rust Toolchain

Execute the standard `rustup` installation script, then activate the pinned toolchain:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup toolchain install 1.96.1
rustup default 1.96.1

```

### Setting Up Python

Ensure your environment meets the minimum version before installing the Python package:

```bash

# Using uv (recommended)

uv venv --python 3.10
source .venv/bin/activate

# Or using standard Python

python3.10 -m venv venv
source venv/bin/activate

```

### Building the Switchyard Server

Compile and install the server binary directly from the workspace:

```bash
cargo install --locked switchyard-server
switchyard-server --help

```

The `--locked` flag respects the `Cargo.lock` file from the repository, ensuring you use the exact dependency versions validated against Rust 1.96.1.

### Configuring Environment Variables

To run a functional server, export your API keys. The README and [`docs/getting_started.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/getting_started.md) specify `OPENROUTER_API_KEY` as a common requirement for routing to external providers:

```bash
export OPENROUTER_API_KEY="sk-or-v1-..."
switchyard-server --config routes.toml --host 127.0.0.1 --port 4000

```

Use the `--dry-run` flag to validate configuration without initiating network connections.

## Summary

- Switchyard requires **Rust 1.96.1** exactly, pinned in [`rust-toolchain.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/rust-toolchain.toml) and enforced across all workspace crates.
- **Python 3.10+** is required only if using the optional Python façade via PyO3.
- Standard system build tools (gcc, make, git) are necessary for compiling native dependencies.
- The optional **`uv`** tool streamlines Python environment management for repository tooling.
- Environment variables like `OPENROUTER_API_KEY` configure runtime routing behavior but are not build-time requirements.

## Frequently Asked Questions

### What Rust version does Switchyard require?

Switchyard requires **Rust 1.96.1** exactly. The repository pins this version in [`rust-toolchain.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/rust-toolchain.toml) to ensure consistent compilation of cryptographic libraries and async runtime code. Installing the latest stable Rust will not suffice; you must install the specific 1.96.1 channel via `rustup`.

### Can I use Python 3.9 with Switchyard?

No. The [`pyproject.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/pyproject.toml) file explicitly declares `requires-python = ">=3.10"`. The PyO3 bindings in [`crates/switchyard-py/Cargo.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-py/Cargo.toml) target the CPython 3.10 API, and earlier versions will fail to load the compiled extension module.

### Is the Python interface required to run the Switchyard server?

No. The stand-alone server compiled from `crates/switchyard-server` is a pure Rust binary that requires no Python runtime. You only need Python if you intend to embed Switchyard as a library within a Python application using the `switchyard_rust` package.

### What environment variables are mandatory to start the server?

No environment variables are strictly required for compilation, but **runtime functionality requires API keys**. The standard quick-start configuration expects `OPENROUTER_API_KEY` to authenticate requests to external LLM providers. Without this variable, the server will start but fail to route inference requests, logging authentication errors to stderr.