Cross-Compiling Rust in a DevContainer

You develop on one platform but ship Rust binaries for others. This page cross-compiles from a devcontainer by adding the rustup target and the matching linker, covering the pure-Rust case and the C-dependency case.

Prerequisites

You need a Rust devcontainer and the target triple you build for.

  • A Rust toolchain in the container.
  • The rustup target triple you want (e.g. aarch64-unknown-linux-gnu).
  • A cross linker for that target if you link C.

Cross-compile prerequisitesAdd the rustup target, a cross linker, cargo config, and build with --target.Add targetrustup target addLinkerinstall cross gccConfigcargo target linkerBuild--target

Step-by-Step Implementation

  1. Add the target triple.
rustup target add aarch64-unknown-linux-gnu
  1. Install a cross linker for that target.
apt-get install -y gcc-aarch64-linux-gnu
  1. Point cargo at the linker.
# .cargo/config.toml
[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"
  1. Build for the target and verify.
cargo build --target aarch64-unknown-linux-gnu && file target/aarch64-unknown-linux-gnu/debug/app

Pure Rust vs C-linked cross-compilePure-Rust cross-compiles with just a target; C dependencies need a cross linker.Pure RustC dependenciesAdd targetrustup target addrustup target addLinkerdefaultcross gccEfforttrivialmoderate

Common Pitfalls

Cross-compile failures are a missing target or the wrong linker.

Cross-compile triageA triage path from a failing cross-build to the right target and linker.Is the rustup target added?NOrustup target add <triple>Does it link C?YESInstall + configure a cross linkerBinary built for the target

SymptomRoot CauseRemediation
error: target not installedrustup target missingrustup target add
linker not foundNo cross linker for the targetInstall gcc- and set it in cargo config
links against host libscargo used the host linkerConfigure the target's linker
Runs on host onlyBuilt for the host triplePass --target

Conclusion

Cross-compiling Rust is rustup target add plus, when C is involved, a matching cross linker configured in .cargo/config.toml. Pure-Rust targets need only the target; C-linked ones need the linker. Either way one devcontainer builds for many platforms.

Pure vs C-linkedPure Rust needs only the target; C-linked needs a cross linker and config.Pure Rustrustup target addcargo --targetNo extra linkerC-linkedCross gcccargo config linkerMatching sysroot

FAQ

How do I build a Rust binary for a different platform? Add the target with rustup target add <triple> and build with cargo build --target <triple>. For pure-Rust programs that is all you need — the toolchain produces a binary for the target from your dev container.

Why does cross-compilation fail when my crate uses C? Because linking C requires a cross linker for the target, and cargo defaults to the host linker. Install the cross toolchain (e.g. gcc-aarch64-linux-gnu) and point cargo at it in .cargo/config.toml under the target section.

Can I cross-compile to musl for static binaries? Yes — add the musl target (e.g. x86_64-unknown-linux-musl) and build against it for a static binary with no glibc dependency. It's a common way to produce portable Rust binaries from a devcontainer for container distribution.