Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Keywords and Statements

The unsafe keyword

Reference for Rust unsafe: the five unsafe superpowers, unsafe blocks, unsafe fn and traits, unsafe impl, unsafe_op_in_unsafe_fn, safety comments and what stays checked.

unsafe marks code where you, not the compiler, guarantee that the rules of Rust are respected. It does not switch off the borrow checker or type checking; it unlocks a short list of operations whose safety the compiler cannot prove.

The keyword has two roles. On a block, function, trait or impl it means "I am relying on a contract here". On a function or trait declaration it means "callers (or implementors) must uphold a contract that is described in the documentation".

Rust
let x = 7;
let p = &x as *const i32;
let y = unsafe { *p };

Try it

Rust Unsafe blocks and unsafe functions

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 Unsafe traits and unsafe impls

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.

Syntax

Rust
unsafe { ... }                     // block
unsafe fn name(...) { ... }        // function with a contract
unsafe trait Name { ... }          // trait with a contract for implementors
unsafe impl Name for Type { ... }  // implementor accepts the contract
unsafe extern "C" { ... }          // foreign block (2024 edition)
#[unsafe(no_mangle)]               // unsafe attributes (2024 edition)

The five operations allowed only in unsafe code: dereference a raw pointer, call an unsafe function or method, access or modify a mutable static, implement an unsafe trait, and access fields of a union.

Usage notes

  • Keep blocks small and put a // SAFETY: comment above each one that states why the contract holds. Document the contract of an unsafe function in a # Safety section.
  • unsafe_op_in_unsafe_fn is a warning in edition 2024: the body of an unsafe fn is not automatically an unsafe block.
  • Undefined behavior includes dangling or unaligned dereferences, data races, invalid values (a bool that is not 0/1), breaking aliasing rules and reading uninitialized memory. The program may misbehave anywhere, not only at the unsafe line.
  • Build safe wrappers. The goal is a safe API whose soundness depends on a small amount of unsafe code. Vec, Rc and Mutex all work this way.
  • Send and Sync are unsafe traits: implementing them manually asserts thread-safety the compiler cannot verify.
  • Mutable statics: taking a reference to a static mut is denied by default since edition 2024 (static_mut_refs); use raw pointers with &raw mut or prefer atomics and Mutex.
  • Tools: run tests under Miri to detect many kinds of undefined behavior in unsafe code. Miri output is read-only here; see the lesson below.