Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Tools

Miri: detecting undefined behavior in Rust

Reference for Miri, the Rust interpreter that detects undefined behavior: install it, run cargo miri test, read its errors and use MIRIFLAGS like Tree Borrows.

Miri is an interpreter for Rust's mid-level intermediate representation (MIR). Instead of compiling your program to machine code, it executes it step by step while tracking every pointer, every allocation and every byte of initialization. When your program does something the language rules forbid, such as reading freed memory, creating an invalid bool or breaking the aliasing rules, Miri stops and reports undefined behavior (UB) with a stack trace.

Safe Rust cannot cause UB, so Miri matters most for unsafe code, for crates that wrap C libraries and for data structures built on raw pointers. It runs your normal tests, which makes it a cheap safety net for code that a normal compiler cannot check.

Terminal
# read-only: Miri runs on your own computer
rustup +nightly component add miri
cargo +nightly miri test
cargo +nightly miri run

Try it

Miri is a Cargo component and is not available in our online editor, so the shell commands above are read-only. The examples below are unsafe programs that Miri accepts: every pointer stays inside one allocation, every read follows a write, and no two live &mut references overlap. Run them on your own machine with cargo +nightly miri run to see a clean pass.

Rust Raw pointers inside one allocation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Two disjoint mutable slices

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

If you changed ptr.add(mid) to ptr.add(mid + 1) and kept the length, Miri would report an out-of-bounds pointer. Ordinary rustc would compile and run the program without complaint, which is exactly the gap Miri closes.

Syntax

Miri is driven through Cargo, plus an environment variable for options.

Terminal
cargo +nightly miri run [-- program args]
cargo +nightly miri test [test filter] [-- test args]
cargo +nightly miri setup          # build the Miri sysroot ahead of time
MIRIFLAGS="-Zmiri-tree-borrows" cargo +nightly miri test
Option (in MIRIFLAGS) Description
-Zmiri-tree-borrows Check pointer aliasing with the Tree Borrows model instead of the default Stacked Borrows. Tree Borrows accepts more real-world code.
-Zmiri-seed=N Fix the seed for Miri's random choices (thread scheduling, address layout) so a failure can be reproduced.
-Zmiri-many-seeds=0..16 Run the program with a range of seeds, to explore different thread interleavings.
-Zmiri-disable-isolation Allow real clock, file system and environment access. By default Miri blocks them to stay deterministic.
-Zmiri-strict-provenance Reject integer-to-pointer casts that lose provenance information.
-Zmiri-ignore-leaks Do not report leaked memory at exit.
-Zmiri-backtrace=full Print a complete backtrace, including std internals.

Result: exit code 0 if the execution is clean. On undefined behavior Miri prints error: Undefined Behavior: ... with the offending line and exits with a non-zero code.

Errors / edge cases: a panic is not UB; Miri reports it like a normal run. A program that Miri cannot interpret (some foreign functions or unsupported system calls) stops with an "unsupported operation" error instead.

Usage notes

  • What it catches: out-of-bounds and dangling pointers, use after free, double free, misaligned access, reading uninitialized memory, invalid values (a bool that is not 0 or 1, a null reference, a bad enum tag), data races, violated aliasing rules, and memory leaks at program exit.
  • Only executed paths are checked. Miri proves nothing about code that your tests never reach. Pair it with good tests, and with fuzzing or property tests.
  • It is slow: expect 10 to 100 times slower than a debug build. Use cargo miri test some_name for focused runs, and reduce loop counts or input sizes under cfg(miri).
  • Skip what cannot run: put #[cfg_attr(miri, ignore)] on tests that need networking, heavy FFI or unsupported syscalls. The cfg(miri) flag is set when Miri is the interpreter, see #[cfg].
  • Nightly only: Miri is installed as a rustup component of the nightly toolchain, even if your project builds with stable. See rustup.
  • Not a proof of soundness. The aliasing rules (Stacked Borrows and Tree Borrows) are experiments, not final language law. Code Miri accepts can still be unsound for another thread schedule, and rare code Miri rejects may be allowed by a future model.
  • Compiler-visible UB is separate. Miri also helps with MaybeUninit and transmute misuse, two classic sources of bugs. See MaybeUninit.