Skip to content

Install Rust on Raspberry Pi and Run Your First Cargo Project

Use rustup to manage a Rust toolchain and Cargo to build a project. First confirm your environment, then compile a small program before introducing ownership, libraries, or GPIO.

Check Raspberry Pi OS and existing Rust tools

Run these on the computer where you intend to compile:

1
2
3
4
5
6
cat /etc/os-release
uname -m
getconf LONG_BIT
command -v rustup
command -v rustc
command -v cargo

On a typical 64-bit Pi OS installation, uname reports aarch64 and user space is 64-bit. These are checks, not an instruction to change the OS. A 64-bit-capable board can still have a 32-bit OS installed.

If Rust is already installed, inspect it before adding another installation:

1
2
3
rustc --version
cargo --version
rustc -vV

The host line in rustc -vV identifies the compiler's host target. Record actual versions when asking for help; this lesson does not require a particular latest release number.

Install Rust and a native linker

For a Raspberry Pi OS development machine, install the usual build tools:

1
2
sudo apt update
sudo apt install build-essential curl ca-certificates

Follow the official Rust installation instructions. The standard Unix installation command is:

1
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

This downloads and executes an installer. Review the official source and command before running it. Run rustup as your regular user, not with sudo. It installs the selected compiler and Cargo into your user environment.

For an unsupported architecture or installation policy that disallows this installer, consult the official alternative installation methods. Do not download a compiler for a different target and assume it will run on your Pi.

Open a fresh terminal after installation. In Bash, you can instead load the generated environment file if it exists:

1
2
3
4
. "$HOME/.cargo/env"
rustup show
rustc --version
cargo --version

Do not mix a system Cargo and a rustup compiler unknowingly. Check command paths and rustup show when versions or components appear inconsistent.

Create the first Cargo project

Choose a writable working directory, then:

1
2
3
cargo new pi_hello
cd pi_hello
cargo run

The official Cargo introduction explains the generated project. Cargo.toml describes the package; src/main.rs contains the binary's source. target/ contains generated build output, not the source you edit.

Open src/main.rs and replace its contents with:

1
2
3
4
fn main() {
    let device = "Raspberry Pi";
    println!("Hello, {device}!");
}

Run cargo run again. The program's standard output should be:

1
Hello, Raspberry Pi!

Cargo also prints build/run information, usually on standard error. The string does not detect your hardware; the same program can run on another supported computer.

Distinguish build, check, run, and test

1
2
3
4
cargo check
cargo build
cargo run
cargo test

check checks the program without producing the final executable. build produces it; run builds as needed and executes it; test runs the project's tests. A test command reporting zero tests is not proof that you tested program behaviour.

Edit the program so it produces the wrong greeting and rerun it. This first exercise is manual observation; later lessons introduce executable assertions and reusable functions.

Troubleshoot the first build

cargo or rustc: command not found: open a new shell, check the installation's environment file, and inspect command paths. Reinstalling repeatedly does not fix a shell that has not loaded the tools' path.

Linker cc not found: confirm build-essential installed successfully and check command -v cc. Rust still needs the native linker for this Linux executable. The Rust book's installation chapter explains this requirement.

Exec format error or incompatible binary: check OS architecture and rustc's host target. Copying an executable from a different architecture is not the same as a native build.

No Cargo.toml found: run Cargo from the pi_hello project directory, not its parent or an unrelated terminal location.

Build process killed: inspect memory pressure and kernel logs before changing toolchains or enabling overclocking. See memory-pressure diagnosis.

What you have established

You can locate the toolchain, distinguish source from build output, and build/run a standard-library program. This is not a GPIO project or a performance result, and no Raspberry Pi hardware testing is claimed.

The next planned lesson introduces variables, types, functions, and control flow before ownership and borrowing. Until it is published, continue with the Rust book's common programming concepts.

Rust course overview

Donate