# Build Requirements for iroh: A Complete Guide to Compiling from Source > Learn the essential build requirements for iroh. Discover the necessary Rust version, C compiler, pkg-config, and optional dependencies to compile iroh from source. - Repository: [number zero/iroh](https://github.com/n0-computer/iroh) - Tags: how-to-guide - Published: 2026-06-21 --- **Building iroh requires Rust 1.75 or later, a working C compiler toolchain, and `pkg-config` on Unix systems, with optional OpenSSL headers and the Protocol Buffers compiler for specific features.** The iroh distributed systems library from n0-computer provides peer-to-peer networking primitives written in pure Rust. Understanding the build requirements for iroh ensures you can compile the core library, DNS utilities, and relay server from source without encountering missing dependency errors. ## Core Build Requirements ### Rust Toolchain The minimum supported Rust version (MSRV) is defined in the `rust-version` field of [`iroh/Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/iroh/Cargo.toml). As of the latest stable release, **Rust 1.75** is required. Install the toolchain via `rustup`: ```bash rustup install stable rustup default stable ``` Cargo is included with the Rust toolchain and handles all crate dependencies automatically. ### C/C++ Build Tools Several dependencies—notably the `ring` crate used for cryptographic operations—compile native C code during the build process. You must have a working C compiler available: - **Linux**: `gcc` or `clang` - **macOS**: Xcode Command Line Tools (`clang`) - **Windows**: Microsoft Visual C++ Build Tools (MSVC) ### pkg-config On Linux and macOS, the build system requires `pkg-config` to locate system libraries. This utility is typically installed by default on macOS with Xcode tools, but on Linux distributions you may need to install it explicitly: ```bash # Debian/Ubuntu sudo apt-get install pkg-config # macOS (if not present) brew install pkg-config ``` ## Optional Dependencies by Feature ### OpenSSL Development Headers If you enable the optional `openssl` feature flag in [`iroh/Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/iroh/Cargo.toml), you must provide OpenSSL development headers and libraries. This feature is disabled by default in favor of `rustls`. Install the required packages: - **Debian/Ubuntu**: `libssl-dev` - **macOS**: `openssl` via Homebrew (with appropriate `PKG_CONFIG_PATH` export) - **Windows**: OpenSSL binaries via vcpkg or Strawberry Perl ### Protocol Buffers Compiler The `iroh-dns` crate defined in [`iroh-dns/Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/iroh-dns/Cargo.toml) uses `build = "build.rs"` to compile `.proto` files at build time. You must install `protoc` version 3.14 or higher: ```bash # Debian/Ubuntu sudo apt-get install protobuf-compiler # macOS brew install protobuf # Verify version protoc --version ``` The `protobuf-codegen` crate is invoked automatically by Cargo once the compiler is present. ## Cross-Compilation Targets The iroh codebase supports cross-compilation to numerous targets including `x86_64-unknown-linux-musl`, Android architectures, and various ARM boards. The CI configuration files in `.github/workflows/*.yml` demonstrate the exact setup. Add your target toolchain: ```bash # Static musl build rustup target add x86_64-unknown-linux-musl # Android rustup target add aarch64-linux-android # ARMv7 rustup target add armv7-unknown-linux-gnueabihf ``` For static musl builds, you also need the `musl-tools` package on Debian/Ubuntu or the equivalent musl-gcc wrapper. ## Docker and Build Automation ### Docker Requirements To build the relay server container defined in `docker/`, you need Docker 20.10 or later with `docker-buildx` enabled. The repository provides ready-to-use images but building locally requires: ```bash cd docker docker build -t iroh-relay . ``` For cross-platform images: ```bash docker buildx build --platform linux/amd64,linux/arm64 -t iroh-relay . ``` ### cargo-make The repository includes a [`Makefile.toml`](https://github.com/n0-computer/iroh/blob/main/Makefile.toml) for task automation. Install `cargo-make` to use shortcuts: ```bash cargo install cargo-make cargo make # Builds and tests ``` ## Step-by-Step Build Instructions ### Basic Debug Build Clone the repository and build the workspace: ```bash git clone https://github.com/n0-computer/iroh.git cd iroh cargo build ``` This compiles the core `iroh` crate and all workspace members using your system C compiler for native dependencies. ### Static Binary Release For a fully static Linux binary suitable for deployment: ```bash # Install prerequisites rustup target add x86_64-unknown-linux-musl sudo apt-get install musl-tools # Build cargo build --release --target x86_64-unknown-linux-musl ``` The resulting binary at `target/x86_64-unknown-linux-musl/release/iroh` requires no shared libraries. ### Build with DNS Support If working with the `iroh-dns` crate, ensure `protoc` is installed, then build specifically: ```bash cargo build -p iroh-dns ``` ## Summary - **Rust 1.75+** is mandatory, specified in [`iroh/Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/iroh/Cargo.toml) via the `rust-version` field. - **C compiler** is required for native dependencies like `ring`. - **pkg-config** is necessary on Unix systems for library discovery. - **OpenSSL headers** are only needed if explicitly enabling the `openssl` feature. - **protoc 3.14+** is required to build the `iroh-dns` crate from [`iroh-dns/Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/iroh-dns/Cargo.toml). - Cross-compilation to `musl`, Android, and ARM targets requires additional `rustup` targets and potentially system linkers. ## Frequently Asked Questions ### What is the minimum Rust version required to build iroh? According to the `rust-version` field in [`iroh/Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/iroh/Cargo.toml), you need **Rust 1.75** or later. This minimum version ensures compatibility with dependencies like `quinn` and `rustls` while maintaining stable async trait support. ### Do I need OpenSSL to build iroh? No, OpenSSL is optional. By default, iroh uses `rustls` and the `ring` crate for cryptography. You only need OpenSSL development headers if you explicitly enable the `openssl` feature flag in your [`Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/Cargo.toml) dependencies. ### Can I build iroh for Android or embedded devices? Yes, iroh supports cross-compilation to Android (`aarch64-linux-android`, `armv7-linux-androideabi`) and various ARM boards. You must install the appropriate `rustup target` and provide the Android NDK toolchain for mobile targets. The CI workflows in `.github/workflows/` contain working examples for these builds. ### How do I build a static binary that runs without shared libraries? Use the `x86_64-unknown-linux-musl` target with `musl-tools` installed. Run `rustup target add x86_64-unknown-linux-musl`, install `musl-gcc`, then execute `cargo build --release --target x86_64-unknown-linux-musl`. This produces a statically-linked binary in `target/x86_64-unknown-linux-musl/release/` that runs on any Linux distribution without requiring glibc.