Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Concepts

Rust modules and paths

Reference for Rust modules: mod blocks, paths (crate, self, super), use declarations and re-exports, pub visibility levels, the file layout and name resolution rules.

A module is a named namespace that groups items (functions, types, traits, constants, other modules) and controls their visibility. Every crate has a root module; mod name { ... } declares a child. Items are private to their module (and its descendants) by default, and pub exposes them.

A path names an item. crate::a::b starts at the crate root, self::b at the current module, super::b at the parent, and a plain a::b starts at a name in scope. A use declaration brings a path into scope under a shorter name.

Rust
mod shapes {
    pub fn area(w: f64, h: f64) -> f64 { w * h }
}
use shapes::area;

Try it

Rust Nested modules, pub and paths

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 use, aliases, globs and re-exports

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 Privacy errors are compile errors

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.

Visibility

Modifier Visible from
(none) the current module and its descendants
pub everywhere the parent module is reachable
pub(crate) the whole crate
pub(super) the parent module
pub(self) same as private
pub(in path) the named ancestor module

Visibility applies per item. Making a struct pub does not expose its fields; each field needs its own pub. The variants of a pub enum and the items of a pub trait are public automatically.

File layout

A module declared as mod name; (with a semicolon) loads its body from a file. For a module a in the crate root file (main.rs or lib.rs) the compiler looks for a.rs or a/mod.rs; for a child a::b declared inside a.rs it looks for a/b.rs. The modern style prefers a.rs plus an a/ folder for children over mod.rs. A mod declaration is what adds a file to the crate; a file that is never named by mod is ignored. The #[path = "x.rs"] attribute overrides the lookup. Our runner compiles a single main.rs, so use inline mod name { ... } blocks there.

Name resolution rules

  • Edition 2018+ paths: a use path starts with crate, self, super, a crate name (such as std) or a name in scope. There is no need for extern crate.
  • Two namespaces for values and types: a unit struct and a function can share a name in different namespaces; modules live with types.
  • Prelude: Option, Vec, String, Box, Some, Ok and others are brought in automatically. The edition decides the exact prelude (2024 adds Future and IntoFuture).
  • Shadowing: a local item or use shadows the prelude; a glob import (use a::*) is lower priority than explicit names.
  • Enum variants can be imported: use Color::*; or use Color::{Red, Green};.

Usage notes

  • Group imports by crate: use std::{fmt, io::{self, Read}};.
  • Idiom: import types and traits directly (use std::collections::HashMap;) but call functions through their module (fs::read_to_string) so the origin stays visible.
  • pub use builds a facade: keep a deep internal layout and expose a flat public API from the crate root.
  • Unused imports produce a warning (unused_imports); use ... as _; imports a trait only for its methods, without a name.
  • Cyclic references between modules are fine within a crate; cycles between crates are not.
  • Tests: a #[cfg(test)] mod tests { use super::*; ... } child module sees private items of its parent.