# How to Build iroh from Source: Complete Rust Workspace Guide

> Build iroh from source by cloning the repo, installing dependencies, and running cargo build release. Get optimized iroh, iroh-relay, and iroh-dns-server binaries with this guide.

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

---

**Clone the n0-computer/iroh repository, install OpenSSL and CMake, then run `cargo build --release` to compile the workspace.** This produces optimized binaries including `iroh`, `iroh-relay`, and `iroh-dns-server` in the `target/release/` directory.

iroh is a Rust-based peer-to-peer networking library developed by n0-computer. Building from source requires the Cargo package manager to compile the workspace, which contains the core library and several binary crates located in [`iroh/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/lib.rs), [`iroh-relay/src/main.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/main.rs), and [`iroh-dns-server/src/main.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-dns-server/src/main.rs).

## Prerequisites

Before compiling iroh, ensure you have the required system dependencies. The build process requires **OpenSSL** for optional TLS features and **CMake** for compiling native C code dependencies like the `noq` QUIC implementation.

On Debian/Ubuntu systems, install these with:

```bash
sudo apt install libssl-dev cmake

```

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

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

```

## Cloning the Repository

Clone the official repository and enter the workspace directory:

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

```

The workspace manifest is located at [`Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/Cargo.toml) in the repository root, defining all members including `iroh`, `iroh-relay`, `iroh-base`, and `iroh-dns-server`.

## Building the Workspace

### Development Builds

For development and debugging, compile debug artifacts for all workspace members:

```bash
cargo build

```

This creates unoptimized binaries in `target/debug/`.

### Production-Ready Binaries

To create optimized release binaries:

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

```

This produces executables in `target/release/`:
- `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 `iroh` binary to `~/.cargo/bin` for system-wide access:

```bash
cargo install --path .

```

## Building Individual Components

You can compile specific crates independently using the `-p` flag.

### Compiling the Relay Server

The relay server source is located at [`iroh-relay/src/main.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/main.rs). Build it separately with:

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

```

### Compiling the DNS Server

The DNS server, which resolves `EndpointId`-based names like `dns.iroh.link`, resides in [`iroh-dns-server/src/main.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-dns-server/src/main.rs). Build it with:

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

```

## Cross-Compilation

For non-native targets, the CI pipeline uses `cross`. Install it and specify a target triple:

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

```

## Running the Echo Example

The repository includes an echo protocol demonstrating the core API. The implementation is in [`examples/echo.rs`](https://github.com/n0-computer/iroh/blob/main/examples/echo.rs). After building the workspace, run:

```bash
cargo run --example echo

```

This example starts a server and client, opens a QUIC stream, echoes data, and closes the connection.

## Using the Core Library

When building applications that depend on iroh, reference the core library from [`iroh/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/lib.rs). Here is a minimal client example:

```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

- iroh is a Rust workspace requiring Cargo to build from source according to the n0-computer/iroh repository structure
- Install system dependencies: OpenSSL (`libssl-dev`) and CMake before compiling
- Use `cargo build --release` to compile all binaries to `target/release/`
- Build individual components with `-p iroh-relay` or `-p iroh-dns-server`
- Key source files include [`iroh/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/lib.rs), [`iroh-relay/src/main.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/main.rs), and [`iroh-dns-server/src/main.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-dns-server/src/main.rs)
- Run the echo example with `cargo run --example echo` to verify the build

## Frequently Asked Questions

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

iroh requires the stable Rust channel. The project tracks the latest stable releases, so ensure you have an up-to-date toolchain by running `rustup update` before building.

### Can I build iroh without OpenSSL?

While the core library may compile, OpenSSL is required for TLS features used by the relay and DNS server components. Install `libssl-dev` on Debian/Ubuntu or the equivalent package for your operating system to ensure full functionality.

### Where are the compiled binaries located?

Debug builds appear in `target/debug/`, while release builds are placed in `target/release/`. When running `cargo install --path .`, the binaries are copied to `~/.cargo/bin/` (or your system's equivalent Cargo bin directory).

### How do I build only the iroh client binary without the relay server?

Use the `-p` flag to specify the package: `cargo build -p iroh --release`. This compiles only the core library and associated binary, skipping the relay and DNS server crates.