Cross-Compile Rust for Linux, Windows, and ARM with cargo (2026)

Rust’s cross-compilation story is surprisingly smooth, but the real magic isn’t just getting it to build; it’s how cargo orchestrates the entire toolchain download and configuration for you with minimal fuss.

Let’s see it in action. Imagine you have a simple Rust project, say hello_cross:

// src/main.rs
fn main() {
    println!("Hello from {}!", std::env::consts::OS);
}

By default, cargo build targets your current system. But to build for another, you need to tell cargo about it. This is where "target triples" come in. A target triple is a string that identifies the architecture, vendor, and operating system you’re compiling for. For example, x86_64-unknown-linux-gnu is a common target for 64-bit Linux.

To cross-compile, you’ll use the build.target configuration option in your .cargo/config.toml file or pass --target directly on the command line.

First, you need the target toolchain. This includes the compiler backend (like LLVM) configured for the target, and crucially, the C standard library and linker for that target. rustup handles this beautifully.

To add a target for 64-bit Linux (if you’re not already on Linux) or for a different Linux architecture:

rustup target add x86_64-unknown-linux-gnu

For Windows (64-bit):

rustup target add x86_64-unknown-windows-gnu

And for ARM (e.g., 32-bit ARMv7 for embedded or Raspberry Pi, often using the GNU toolchain):

rustup target add armv7-unknown-linux-gnueabihf

Once rustup has downloaded these, you can tell cargo to use them.

Building for Linux from macOS/Windows:

Let’s build our hello_cross project for Linux.

Add the target:

rustup target add x86_64-unknown-linux-gnu

Build with the target:

cargo build --target x86_64-unknown-linux-gnu

This command instructs cargo to use the Rust toolchain specifically installed for x86_64-unknown-linux-gnu. It will also link against the C standard library and use the GNU linker that rustup downloaded for this target. The resulting executable will be in target/x86_64-unknown-linux-gnu/debug/.

Building for Windows from macOS/Linux:

To build for Windows, you’ll need the MinGW toolchain for linking.

Add the target:

rustup target add x86_64-unknown-windows-gnu

Build with the target:

cargo build --target x86_64-unknown-windows-gnu

The executable will be in target/x86_64-unknown-windows-gnu/debug/. On Windows, this will be a .exe file.

Building for ARM (e.g., Raspberry Pi):

Cross-compiling for ARM often requires a specific C library setup and toolchain. rustup can install the necessary components.

Add the target:
```
rustup target add armv7-unknown-linux-gnueabihf
```
(The hf stands for hardware float support, common on many ARM platforms.)

Build with the target:

cargo build --target armv7-unknown-linux-gnueabihf

The output will be in target/armv7-unknown-linux-gnueabihf/debug/.

Configuration File (.cargo/config.toml)

For frequent cross-compilation, it’s cleaner to put this in your .cargo/config.toml file.

For example, to always build for Linux by default when inside a specific project directory:

# .cargo/config.toml
[build]
target = "x86_64-unknown-linux-gnu"

Or, to configure specific build profiles:

# .cargo/config.toml
[target.x86_64-unknown-linux-gnu]
linker = "x86_64-linux-gnu-gcc" # Example: specify a system-installed linker
rustflags = ["-C", "target-feature=+avx2"] # Example: specific flags for this target

The rustup target add command is the primary mechanism for acquiring the necessary toolchains. It downloads the Rust compiler components (like rustc and cargo itself, but built for that target) and, crucially, the C libraries and linker required for static or dynamic linking on the target OS. Without these, Rust’s FFI (Foreign Function Interface) capabilities, and indeed many standard library functions that rely on C primitives, would be unusable. rustup ensures that when you specify a target, you get the whole supporting ecosystem.

The most surprising thing about cargo’s cross-compilation is how little you actually need to do manually once rustup has the target installed. It automatically finds and uses the correct linker and C library for the target, abstracting away a significant amount of complexity that would otherwise involve manual toolchain setup and environment variable configuration for tools like gcc or clang.

The build.target setting in config.toml is powerful, but it’s important to remember that it only tells cargo which Rust toolchain to use. It doesn’t magically install the C toolchain or libraries if rustup hasn’t already done so via rustup target add. If cargo complains about a missing linker or C headers for your target, it’s almost always because rustup target add didn’t cover all the necessary system dependencies for that specific target triple.

The next step after successfully cross-compiling is often figuring out how to deploy and run these binaries on the target system, which involves understanding cross-distribution compatibility and C library versions.