# How to Set Up a Development Environment for Switchyard

> Easily set up a Switchyard development environment. Install Python, Rust, and uv, then sync dependencies to get started fast. Build with Switchyard today.

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

---

**To set up a development environment for Switchyard, install Python 3.10+, Rust 1.96.1+, and the `uv` package manager, then run `uv sync` in the cloned repository to create a virtual environment with all Python and Rust dependencies.**

Switchyard is a multi-language project that combines Rust libraries, a native server, and Python bindings. Setting up a development environment for Switchyard requires coordinating both the Rust toolchain and Python packaging tools, which is streamlined through the `uv` dependency manager. This guide walks through the complete setup process using the exact specifications found in the [[`INSTALLATION.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/INSTALLATION.md)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/INSTALLATION.md) and [[`DEVELOPMENT.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/DEVELOPMENT.md)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/DEVELOPMENT.md) files from the NVIDIA-NeMo/Switchyard repository.

## Prerequisites

Before cloning the repository, ensure your system meets the following requirements documented in the source code.

### Python 3.10 or Higher

The `nemo-switchyard` package requires **Python 3.10+** to support the modern type hints and async features used in the codebase. Verify your version with `python --version` before proceeding.

### Rust 1.96.1 or Higher

The native server and Rust crates in `crates/libsy/` and `crates/switchyard-py/` require **Rust 1.96.1+**. Install via [rustup](https://rustup.rs/) if you do not have a compatible toolchain.

### uv Package Manager

**uv** is the preferred Python dependency manager for this project. It creates the `.venv` used for development and handles the build backend (maturin) that compiles Rust extensions. Install uv using the official installer:

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

```

### Git

Required to clone the repository and install pre-commit hooks.

## Clone the Repository

Fetch the source code from GitHub and navigate into the project directory:

```bash
git clone https://github.com/NVIDIA-NeMo/Switchyard.git
cd Switchyard

```

The repository contains the Rust workspace in `crates/`, Python bindings in `crates/switchyard-py/`, and the [`pyproject.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/pyproject.toml) file that defines the Python package metadata and dependency groups.

## Create the Development Virtual Environment

Run `uv sync` to create the development virtual environment. This command reads the [`pyproject.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/pyproject.toml) file, resolves dependencies, creates a `.venv` directory, and installs the core package along with development tools.

```bash
uv sync

```

By default, `uv sync` installs the "dev" dependency group, which includes **pytest**, **ruff**, **mypy**, and **pre-commit**. Alternatively, specify the group explicitly:

```bash
uv sync --group dev

```

The sync process also triggers **maturin** to build the Rust extensions (powered by PyO3), compiling the `switchyard-py` crate into a native Python module available as `switchyard.libsy`.

## Install Git Hooks (Optional but Recommended)

Maintain code quality by installing pre-commit hooks that run **ruff** linting and **commitlint** on every commit. Use `uvx` to execute the pre-commit tool without installing it globally:

```bash
uvx pre-commit install --install-hooks \
    --hook-type pre-commit --hook-type commit-msg

```

These hooks ensure the codebase stays clean and commit messages follow the project's conventional commit format before they reach the repository.

## Activate the Environment and Verify the Build

Activate the virtual environment to access the compiled extensions and development tools:

```bash
source .venv/bin/activate

```

After activation, verify the installation by running the test suites and static analysis tools.

### Run the Rust Test Suite

Execute the workspace tests to verify the core Rust libraries:

```bash
cargo test --workspace

```

This validates the routing algorithms and server logic defined in `crates/libsy/` and related crates.

### Run the Python Test Suite

Use `uv run` to execute pytest within the managed environment:

```bash
uv run pytest tests/ -v

```

### Run Static Analysis

Check Python code quality with the configured linters:

```bash
uv run ruff check .
uv run mypy switchyard

```

Successful execution of these commands confirms that your development environment correctly builds both the Rust extensions and Python package.

## Additional Development Workflows

Once the basic environment is functional, you can perform advanced development tasks.

### Embed the Library in Python

To rebuild the Python bindings from source after modifying Rust code:

```bash
uv run maturin develop

```

You can then import and use the routing library:

```python
from switchyard.libsy import LlmResponse, Step
from switchyard.libsy.algorithms import stage_router

algorithm = stage_router(
    "capable", "efficient",
    picker="efficient_first",
    confidence_threshold=0.5,
)

```

### Run the Standalone Server

Install and run the native Rust server using Cargo:

```bash
cargo install --locked switchyard-server
switchyard-server --config routes.toml --host 127.0.0.1 --port 4000

```

Refer to the "Path 3" section of the README and [`docs/routing_algorithms/overview.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/routing_algorithms/overview.md) for TOML configuration examples and routing algorithm documentation.

## Summary

- **Install prerequisites**: Python 3.10+, Rust 1.96.1+, uv, and Git.
- **Clone** the NVIDIA-NeMo/Switchyard repository and run `uv sync` to create the development virtual environment.
- **Activate** the environment with `source .venv/bin/activate` to access the `switchyard` Python package and compiled Rust extensions.
- **Verify** the setup by running `cargo test --workspace`, `uv run pytest tests/`, and the ruff/mypy linters.
- **Optional**: Install pre-commit hooks with `uvx pre-commit install` to enforce code quality on every commit.
- **Develop**: Use `uv run maturin develop` to rebuild Python bindings and `cargo install --locked switchyard-server` to test the standalone proxy.

## Frequently Asked Questions

### What is the minimum Rust version required for Switchyard development?

Switchyard requires **Rust 1.96.1 or higher** to compile the server and core libraries located in `crates/libsy/` and `crates/switchyard-py/`. This version ensures compatibility with the async runtime and dependency crates used in the routing algorithms.

### Why does Switchyard use uv instead of pip or conda?

The project uses **uv** because it is a fast Python dependency manager that also handles the creation of the `.venv` and coordinates with **maturin** to build Rust extensions. According to the [`pyproject.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/pyproject.toml) configuration, `uv sync` installs both Python dependencies (pytest, ruff, mypy) and triggers the compilation of the PyO3 bindings in a single command.

### How do I run tests for both Python and Rust components?

Run `cargo test --workspace` from the repository root to test the Rust crates. For Python, execute `uv run pytest tests/ -v` or activate the virtual environment and run `pytest` directly. Both test suites should pass before submitting contributions to the codebase.

### Can I develop Switchyard without installing the pre-commit hooks?

Yes, the pre-commit hooks are optional but strongly recommended. They automate **ruff** linting and **commitlint** checks to ensure code quality. If you skip them, you must manually run `uv run ruff check .` and ensure your commit messages follow the conventional format before opening a pull request.