The Rust on ESP Book

Toolchain Installation

Rust Installation

Make sure you have Rust installed. If not, see the instructions on the rustup website.

🚨 Warning: When using Unix based systems, installing Rust via a system package manager (e.g. brew, apt, dnf, etc.) can result in various issues and incompatibilities, so it's best to use rustup instead.

When using Windows, make sure you have installed one of the ABIs listed below. For more details, see the Windows chapter in The rustup book.

• MSVC: Recommended ABI, included in the list of rustup default requirements. Use it for interoperability with the software produced by Visual Studio.

  When in doubt this is what you want to use.

• GNU: ABI used by the GCC toolchain. Install it yourself for interoperability with the software built with the MinGW/MSYS2 toolchain.

See also alternative installation methods.

RISC-V Devices

To build Rust applications for the Espressif chips based on RISC-V architecture (if you're unsure what your device is, see hardware overview), do the following:

1. Install the proper toolchain with the rust-src component:

   • You can use either stable or nightly:

     rustup toolchain install stable --component rust-src
     

     or

     rustup toolchain install nightly --component rust-src
     

   ⚠️ Note: Other components such as rustfmt, clippy or rust-analyzer are not required, but they are highly recommended.

2. Install the target:

   rustup target add riscv32imc-unknown-none-elf # For ESP32-C2 and ESP32-C3
   rustup target add riscv32imac-unknown-none-elf # For ESP32-C6 and ESP32-H2
   

   Those targets are currently Tier 2. Note the different flavors of riscv32 targets in Rust covering different RISC-V extensions.

If you are not going to use ESP32, ESP32-S2 or ESP32-S3 you are done and can skip to Tooling Installation.

Xtensa Devices

As mentioned in hardware overview ESP32, ESP32-S2 and ESP32-S3 are based on Xtensa architecture. If you are going to target these chips you will need to use a fork of the Rust compiler for now.

espup is a tool that simplifies installing and maintaining the toolchains required to develop Rust applications for these targets.

1. Install espup:

   cargo install espup --locked
   

   You can also directly download pre-compiled release binaries or use cargo-binstall.
2. Install all necessary toolchains for all supported Espressif targets by running:

   espup install
   

3. On Unix systems, set up the Environment Variables: See the different methods in espup Readme. Windows users don't need to do anything else.

What espup Installs

To enable support for Espressif targets, espup installs:

• Espressif Rust fork with support for Espressif targets
• stable toolchain with support for RISC-V targets
• LLVM fork with support for Xtensa targets
• GCC toolchain that links the final binary

The forked compiler can coexist with the standard Rust compiler, allowing both to be installed on your system. The forked compiler is invoked when using any of the available overriding methods.