Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Concepts

Rust orphan and coherence rules

Reference for Rust coherence: the orphan rule, overlapping impls, blanket impls, the newtype workaround, fundamental types and why you cannot implement foreign traits for foreign types.

Coherence is the guarantee that for any type and trait there is at most one implementation the compiler can pick. Without it, two crates could implement the same trait for the same type differently and the program's behavior would depend on which crate was linked. Rust enforces coherence with two checks: the orphan rule and the overlap check.

The orphan rule says: you may write impl Trait for Type only if the trait or the type (roughly) is defined in your own crate. Implementing a foreign trait for a foreign type is an error, because neither you nor the other crates own the pair.

Rust
// Allowed: local trait, foreign type.
trait Describe { fn describe(&self) -> String; }
impl Describe for i32 { fn describe(&self) -> String { format!("int {self}") } }

Try it

Rust Local trait on foreign types, local type with foreign trait

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 The rule rejects a foreign pair

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 The newtype workaround

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.

The rules

An impl<P1..=Pn> Trait<T1..=Tn> for T0 is accepted when at least one of T0..=Tn is a local type, and no uncovered type parameters appear before it. In plain terms:

Impl Allowed? Why
impl LocalTrait for i32 yes the trait is local
impl Display for Local yes Local is local
impl From<Local> for String yes Local appears as a trait parameter
impl Display for Vec<i32> no neither is local
impl<T> Display for T no uncovered T stands for any (possibly foreign) type
impl<T> LocalTrait for T yes blanket impl of a local trait
impl<T> From<T> for Local<T> yes Local<T> is local and T is covered by it

Some pointer types are fundamental: &T, &mut T, Box<T> and Pin<T> count as local when T is local. So impl Display for Box<Local> is not blocked by the orphan rule.

Overlap

Even local impls must not overlap: two impls that could apply to the same type. A blanket impl<T: Display> Describe for T conflicts with impl Describe for i32, because i32 is Display. Rust does not yet support specialization on stable, so you pick one design.

The compiler is also conservative about the future: an upstream crate may add a trait impl in a later version, so you cannot assume Vec<Local> will never implement a foreign trait on its own unless the language rules guarantee it. This is why blanket impls over foreign traits are so restricted.

Usage notes

  • Newtype pattern: wrap the foreign type in a tuple struct, implement what you need on it, and optionally forward methods with Deref or AsRef.
  • Extension traits: define your own trait with methods and implement it for the foreign type (trait StrExt { ... } impl StrExt for str). This is how crates add methods to str or Iterator.
  • Adding an impl is semver-sensitive. Adding a blanket impl, or a trait impl for an existing public type, can break downstream code; library authors treat it as a breaking change unless it is covered by the rules.
  • Library tip: implement the standard traits (Debug, Clone, Display, From, Default) for your public types so users never need a workaround.
  • #[derive] produces local impls and therefore always satisfies the orphan rule for your own types.
  • Error E0117 reports a violated orphan rule; E0119 reports conflicting (overlapping) impls; E0210 reports an uncovered type parameter.