In Rust, what do paths beginning with `crate::`, `self::` and `super::` resolve from, and when do you use each?
answer
- absolute versus relative
- root, current, parent
- use paths relative since 2018
- super cannot leave the crate
basics
~20 scrate:: 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 sA 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 linesmod 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
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.
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.
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.
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.