# How to Build iroh from Source: Complete Guide to Compiling the Rust Networking Stack

> Learn how to build iroh from source with this complete guide. Follow simple steps to compile the Rust networking stack for your project.

- Repository: [number zero/iroh](https://github.com/n0-computer/iroh)
- Tags: how-to-guide
- Published: 2026-06-23

---

**To build iroh from source, install the Rust toolchain, clone the n0-computer/iroh repository, and run `cargo build --release --workspace` to compile the core library and binary crates including the relay server and DNS server.**

The iroh project is a Rust workspace that implements public-key dialing, QUIC transport, and high-level networking APIs. Whether you are developing applications with the core library or deploying infrastructure components, building iroh from source provides access to the latest features in the `n0-computer/iroh` repository.

## Prerequisites

Before compiling iroh, ensure your system has the required dependencies. The build process requires **OpenSSL** development libraries and **CMake** for compiling native code dependencies like the QUIC implementation.

On Debian or Ubuntu systems, install the required packages:

```bash
sudo apt update
sudo apt install libssl-dev cmake

```

You also need the Rust toolchain. Install it using rustup:

```bash
curl https://sh.rustup.rs -sSf | sh -s -- -y
source $HOME/.cargo/env

```

## Understanding the Workspace Structure

The iroh repository is organized as a Cargo workspace defined in the root [`Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/Cargo.toml). The workspace contains multiple crates that share a unified dependency graph.

Key components include:

- **`iroh`** – The core library implementing the public-key dialing and QUIC transport API ([`iroh/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/lib.rs))
- **`iroh-relay`** – Relay client and server for the public relay network ([`iroh-relay/src/main.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/main.rs))
- **`iroh-dns-server`** – DNS server resolving EndpointId-based names ([`iroh-dns-server/src/main.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-dns-server/src/main.rs))
- **`iroh-base`** – Shared types like `EndpointId` and `RelayUrl` ([`iroh-base/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-base/src/lib.rs))

## Building the Complete Workspace

To compile all crates in the workspace, clone the repository and run the build command.

First, clone the source:

```bash
git clone https://github.com/n0-computer/iroh.git
cd iroh

```

For development builds with debug symbols:

```bash
cargo build

```

For optimized, production-ready binaries:

```bash
cargo build --release --workspace

```

The release command generates optimized binaries in `target/release/`, including:

- `target/release/iroh` – Main command-line client
- `target/release/iroh-relay` – Relay server executable
- `target/release/iroh-dns-server` – DNS server executable

## Installing the Client Binary

To install the main `iroh` binary to your Cargo bin directory (`~/.cargo/bin`), use:

```bash
cargo install --path .

```

This makes the `iroh` command available in your PATH, assuming `~/.cargo/bin` is in your environment.

## Building Specific Components

When you only need individual components rather than the entire workspace, target specific packages with the `-p` flag.

To build only the relay server:

```bash
cargo build -p iroh-relay --release

```

To build only the DNS server:

```bash
cargo build -p iroh-dns-server --release

```

This approach reduces compile times when you do not need the complete suite of tools.

## Cross-Compilation

The iroh CI pipeline uses `cross` for building non-native targets. To cross-compile for platforms like ARM64 Linux, first install the tool:

```bash
cargo install cross

```

Then specify the target triple and package:

```bash
cross build --release --target aarch64-unknown-linux-gnu -p iroh-relay

```

This produces an ARM64 binary without requiring a local ARM toolchain.

## Running the Echo Example

The repository includes an example demonstrating the core API. Located at [`examples/echo.rs`](https://github.com/n0-computer/iroh/blob/main/examples/echo.rs), this program starts a server and client, opens a QUIC stream, and echoes data between them.

After building the workspace, run the example:

```bash
cargo run --example echo

```

The example code showcases how to use the iroh library to establish connections:

```rust
// Minimal client using the iroh core library
use iroh::{Endpoint, Router, ProtocolHandler, Connection};
use std::sync::Arc;

const ALPN: &[u8] = b"iroh-example/echo/0";

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Bind a local endpoint
    let endpoint = Endpoint::bind().await?;

    // Connect to a remote peer (replace with a real address)
    let conn = endpoint.connect("127.0.0.1:9999".parse()?, ALPN).await?;

    // Open a bidirectional QUIC stream
    let (mut send, mut recv) = conn.open_bi().await?;

    // Send a message and read the echo
    send.write_all(b"Hello, iroh!").await?;
    send.finish()?;
    let response = recv.read_to_end(1024).await?;
    assert_eq!(response, b"Hello, iroh!");

    // Close everything cleanly
    conn.close(0u32.into(), b"bye!");
    endpoint.close().await;
    Ok(())
}

```

## Summary

Building iroh from source requires the Rust toolchain and standard development dependencies. Key takeaways include:

- Run `cargo build --release --workspace` to compile all binaries including `iroh`, `iroh-relay`, and `iroh-dns-server`
- Use `cargo install --path .` to add the iroh client to your local Cargo bin directory
- Target individual crates with `-p iroh-relay` or `-p iroh-dns-server` to reduce build times
- Install `libssl-dev` and `cmake` before building to satisfy native dependencies
- Execute `cargo run --example echo` to verify your build and explore the API

## Frequently Asked Questions

### What version of Rust is required to build iroh?

Iroh requires the Rust stable channel. The project maintains compatibility with recent stable releases, and you should ensure your toolchain is up to date by running `rustup update` before building from source.

### How do I build only the iroh relay server without the other components?

Use the package-specific build flag: `cargo build -p iroh-relay --release`. This compiles only the `iroh-relay` crate and its dependencies, producing the binary at `target/release/iroh-relay` without building the DNS server or other workspace members.

### Where are the compiled binaries located after building iroh from source?

Debug builds place binaries in `target/debug/`, while release builds place them in `target/release/`. The main client binary appears as `target/release/iroh`, with additional executables for `iroh-relay` and `iroh-dns-server` in the same directory.

### Can I build iroh without OpenSSL?

OpenSSL is required for optional TLS features within the codebase. While you may be able to compile certain crates without it, a full build of the workspace including networking components requires the OpenSSL development libraries (`libssl-dev` on Debian/Ubuntu) to be present on your system.