skip to content

Paths and Imports

Paths start at crate, self or super, use brings names into scope and pub use re-exports them. Interviewers ask how to shape a crate's public API with re-exports.

on this pageshow

questions

5

In Rust, what do paths beginning with `crate::`, `self::` and `super::` resolve from, and when do you use each?

level: juniorimportance: must knowfreq 65%

answer

  1. absolute versus relative
  2. root, current, parent
  3. use paths relative since 2018
  4. super cannot leave the crate

basics

~20 s

crate:: starts at the crate root, self:: at the current module and super:: at its parent. Use crate:: for distant items, super:: for a parent or sibling, and self:: only to stress that a name is local.

solid answer

~40 s

A Rust path names an item in the module tree. `crate::` is the absolute form: it starts at the crate root (`lib.rs` or `main.rs`), so it reads the same from every module. `self::` starts at the current module, and `super::` at the parent; `super::super::` climbs further, but never above the crate root (rustc reports E0433, too many leading `super` keywords). A path with no qualifier is relative too: its first segment must be in scope in the current module, an item, an import or a prelude name such as a dependency crate. Since the 2018 edition this holds for `use` declarations as well, so `use shapes::Point;` inside a submodule fails with E0432 when `shapes` lives at the root. I reach for `crate::` across the tree and `super::` for a close neighbour.

code

rust · 23 lines
rust
mod geometry {
    fn scale(v: f64) -> f64 { v * 2.0 }   // private to geometry
    pub mod shapes {
        pub struct Point { pub x: f64, pub y: f64 }
        pub mod transform {
            use super::Point;              // geometry::shapes::Point
            use super::super::scale;       // private fn of an ancestor is visible here
            pub fn double(p: &Point) -> Point { Point { x: scale(p.x), y: scale(p.y) } }
        }
    }
    pub mod render {
        use crate::geometry::shapes::{Point, transform};
        pub fn describe(p: &Point) -> String {
            let d = transform::double(p);
            format!("({}, {})", d.x, d.y)
        }
    }
}
fn main() {
    use geometry::shapes::Point;
    let p = Point { x: 1.0, y: 2.5 };
    println!("{}", geometry::render::describe(&p));
}

go deeper

for a junior

Know the three starting points: crate:: is the crate root, self:: the current module, super:: the parent. Be able to rewrite a long path either way.

for a middle

Explain why a plain name in a use declaration is relative since 2018, why outer-module items are not in scope in a nested module, and what E0432 and E0433 mean.

for a senior

In review, prefer crate:: across branches and super:: for neighbours, and flag deep super chains that tie a file to its depth or 2015-style imports.

for a principal

Paths carry no lead decision on their own; the judgment shows in keeping the internal tree shallow enough that crate:: paths stay readable and stable as modules move.

## What a path is A **path** is a sequence of names separated by `::` that leads to an item in a crate's **module tree**: a module, struct, enum, function, trait, constant or macro. Every crate has one root module, the file rustc starts from (`src/lib.rs` for a library, `src/main.rs` for a binary), and every `mod` adds a node under it. Paths appear in two places: in expressions and types (`geometry::shapes::Point { x: 1.0, y: 2.0 }`) and in `use` declarations, which bind a short local name to a longer path. The first segment decides where resolution starts. Four starting points matter in everyday code: | First segment | Starts at | Kind | |---|---|---| | `crate::` | the crate root | absolute | | `self::` | the current module | relative | | `super::` | the parent of the current module | relative | | a plain name | whatever that name is in the current scope | relative | ## `crate::`, the absolute path `crate::geometry::render::describe` means the same thing in every module of the crate, because it starts at the root. That makes it the safest choice when the target is far away in the tree, and it survives moving the calling code to another module. It never names a dependency: `crate` is always the crate being compiled. A path that starts with a bare `::` is different again: it reaches into the **extern prelude** (the dependency crates), so `::std::mem::swap` names the `std` crate. ## `self::` and `super::`, the relative paths - `self::helper()` calls `helper` in the current module. Since the 2018 edition a plain `helper()` resolves the same way, so `self::` mostly serves to make locality explicit, for example when a module shares its name with a dependency. - `super::Point` names `Point` in the parent module. Inside a `transform` module nested in `shapes`, `super::Point` reaches `shapes::Point` without spelling the whole path from the root. - `super::super::scale` climbs two levels. Repetition is allowed after a leading `super` or `self`, as in `self::super::super::scale`. - `super` cannot climb above the crate root. Written in the root module, `super::a::f()` fails with **E0433**, "too many leading `super` keywords within `crate`". A child module can name its ancestors' private items through these paths, because privacy lets a module see everything its ancestors declare; how `pub` and its restricted forms work is the subject of the visibility lesson. ## Plain names and the 2018 change A path whose first segment carries no qualifier is resolved in the **current scope**: items declared in this module, names imported into it with `use`, and the preludes (the standard prelude, built-in types, and the extern prelude of dependency crates). Items declared in an outer module are not in scope in a nested one. That is the trap behind a common review comment: 1. The crate root declares `mod shapes` and `mod render`. 2. Inside `render`, someone writes `use shapes::Point;`. 3. rustc 1.99 rejects it with **E0432**, unresolved import `shapes`, and suggests `use crate::shapes::Point;`. In the 2015 edition `use` paths started at the crate root, so that line used to compile; the 2018 edition made `use` paths relative like every other path, and the compiler's note still points at that change. Code copied from 2015-era material is the usual source of this error. ## Choosing between them - Prefer `crate::` for items in a different branch of the tree; it reads unambiguously in review and does not break when the importing module moves. - Prefer `super::` for the parent module or a sibling: a `transform` module reaching its parent's `Point`, or a module's tests reaching the code under test. - Use a plain relative path for children of the current module (`shapes::point::Point` written in the module that declares `shapes`). - Keep `self::` for clarity, or inside braces: `use crate::geometry::{self, Point};` binds both the module and the struct. Deep chains such as `super::super::super::x` are a smell: they couple a file to its exact depth, and `crate::` paths are usually clearer. ## Imports inside functions A `use` declaration does not have to sit at the top of a module. It may appear inside a function body or any block, and its names are then in scope only there. The same path rules apply: `use super::shapes::Point;` inside a function in `render` still starts from `render`'s parent, because a function body belongs to the module that contains it. Block-level imports keep a rarely needed name, such as an enum's variants for one `match`, from leaking into the whole module, and they make clear at a glance which function depends on which part of the tree.

  • Why does `use shapes::Point;` inside `mod render` fail with E0432 when `shapes` is declared at the crate root?
    Since the 2018 edition `use` paths are relative to the current module, and items of an outer module are not in scope inside a nested one. So `shapes` is unknown inside `render`. Write `use crate::shapes::Point;` or `use super::shapes::Point;`; rustc's own help suggests the `crate::` form.
  • What does rustc report for `super::a::f()` written in the crate root module?
    E0433, "too many leading `super` keywords within `crate`". The root has no parent, so `super` cannot be resolved there; use `crate::a::f()` or the plain relative `a::f()` instead.
  • When is `self::` still worth writing in a Rust 2024 crate?
    Rarely for resolution, because a plain name already starts at the current module. It is useful to show that a name is local when the module shares its name with a dependency, and inside braces, where `use crate::geometry::{self, Point};` binds the module `geometry` beside `Point`.

  • crate:: names a dependency listed in Cargo.toml.
  • super:: calls the parent type's method, like a superclass call.
  • In edition 2024, use paths always start from the crate root.
  • super::super:: can climb above the crate root into a dependency.
  • self:: refers to the current struct instance.
open as a page

How does `pub use` let a Rust library expose `geometry::Point` and a `geometry::prelude` when `Point` is defined deep inside a private module?

level: middleimportance: must knowfreq 55%

basics

~20 s

A pub use at the crate root, such as pub use shapes::point::Point, publishes the item as geometry::Point while it stays defined in a private module. A pub mod prelude of re-exports gives users one glob import.

open as a page

In Rust, why do `use crate::shapes::Point;` and `use crate::svg::Point;` in one module fail with E0252, and how do you fix it?

level: middleimportance: should knowfreq 45%

basics

~20 s

Each module holds one binding per name in each namespace, and both imports bind Point in the type namespace, so rustc reports E0252 at the second use. Rename one with as, or import the parent module and write svg::Point.

open as a page

In Rust, when `use shapes::*;` and `use plot::*;` both export `Point`, when does rustc report E0659, and what outranks a glob import?

level: seniorimportance: should knowfreq 30%

basics

~20 s

Conflicting glob imports compile until the name is used; then rustc reports E0659, Point is ambiguous. A local item or an explicit use silently outranks any glob, and globs in turn outrank the standard prelude.

open as a page

A Rust binary declares `mod geometry` and depends on a crate also named `geometry`; what does `use geometry::origin;` resolve to in each module?

level: seniorimportance: nice to knowfreq 25%

basics

~20 s

At the root, the local mod geometry shadows the crate, so the import fails with E0432 if the module lacks origin; in nested modules it reaches the dependency. Write ::geometry for the crate and crate::geometry for the module.

open as a page