Unsafe Rust: what it is and is not

Why does unsafe exist?

The compiler's checks are conservative: they reject some programs that are actually correct, because it cannot prove them safe. And some jobs are impossible without lower-level access: talking to hardware, calling C libraries, or building fast data structures like Vec itself. unsafe is the escape hatch for these cases. Most Rust programmers rarely write it, but every Rust programmer benefits from understanding it.

The five extra abilities

Inside an unsafe block or unsafe function you may do exactly five extra things:

1. Dereference a raw pointer (*const T or *mut T).
2. Call an unsafe function, including functions from C through FFI.
3. Access or modify a mutable static variable.
4. Implement an unsafe trait (such as Send or Sync by hand).
5. Access the fields of a union (a C-style type that stores several kinds of data in the same memory).

Undefined behaviour (UB) means the program breaks a rule the compiler relies on, such as reading freed memory or creating two &mut to the same value. After UB, anything can happen: crashes, wrong results, or security holes, sometimes only in release builds. The whole point of safe Rust is that UB is impossible; inside unsafe, avoiding it is your job.

Raw pointers

let mut x = 10;
let p1 = &x as *const i32;     // creating raw pointers is safe
let p2 = &mut x as *mut i32;

unsafe {
    *p2 += 5;                   // dereferencing them is not
    println!("{}", *p1);        // 15
}

Safe abstractions

The key idea: wrap a small unsafe block inside a function whose public API is safe, and make sure no caller can trigger UB through it. The standard library does this everywhere. For example, slice::split_at_mut returns two non-overlapping &mut halves of one slice; the borrow checker cannot see that they do not overlap, so the implementation uses unsafe internally, but callers use it safely.

/// Returns the item at index i without bounds checks.
///
/// # Safety
/// The caller must ensure i < v.len().
unsafe fn get_fast(v: &[u32], i: usize) -> u32 {
    // SAFETY: the caller promised i is in bounds.
    unsafe { *v.get_unchecked(i) }
}

fn sum_first_three(v: &[u32]) -> u32 {
    assert!(v.len() >= 3);
    // SAFETY: we just checked that indexes 0, 1 and 2 exist.
    unsafe { get_fast(v, 0) + get_fast(v, 1) + get_fast(v, 2) }
}

FFI: calling C code

FFI (foreign function interface) lets Rust call functions written in C, and C call Rust. The compiler cannot check C code, so calls are unsafe. In the 2024 edition, extern blocks themselves must be written unsafe extern, to make clear that the declarations are promises you are making.

unsafe extern "C" {
    fn abs(input: i32) -> i32;     // from the C standard library
}

fn main() {
    let n = unsafe { abs(-7) };
    println!("{n}");               // 7
}

Tools and habits

• Keep unsafe blocks as small as possible, ideally a line or two.
• Write a // SAFETY: comment above each block explaining why it is sound.
• Run tests under Miri (cargo +nightly miri test), an interpreter that detects many kinds of undefined behaviour.
• Prefer a well-tested crate that already wraps the unsafe code.
• Some teams forbid unsafe in application code with #![forbid(unsafe_code)] at the top of the crate.

Common misunderstandings

• "unsafe means the code is dangerous." It means the compiler cannot check it; it can still be correct.
• "unsafe turns off the borrow checker." It does not.
• "Writing unsafe makes code faster." Rarely; safe Rust is usually just as fast. Measure first.
• "Using a crate with unsafe inside makes my code unsafe." Not if the crate's safe API is sound, as with std.