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.
# 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.
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.
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.
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
boolthat 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_namefor focused runs, and reduce loop counts or input sizes undercfg(miri). - Skip what cannot run: put
#[cfg_attr(miri, ignore)]on tests that need networking, heavy FFI or unsupported syscalls. Thecfg(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
MaybeUninitandtransmutemisuse, two classic sources of bugs. SeeMaybeUninit.