Rust Module

A Rust module is a namespace that encapsulates code items—such as functions, structs, traits, impl blocks, and other modules—to establish scope boundaries and control visibility. Modules form a hierarchical tree structure originating from a crate root (typically src/lib.rs or src/main.rs), allowing developers to partition code logically and manage namespace collisions.

Inline Module Declaration

Modules are defined using the mod keyword. An inline module contains its implementation directly within a block in the same file.

mod network {
    // Private by default
    fn connect() {}

    // Public submodule
    pub mod tcp {
        // Public function
        pub fn send() {}
    }
}

File System Mapping

When a module is declared without a code block, the Rust compiler (rustc) defers the module’s definition to an external file. The compiler resolves the module tree by looking for files that match the module’s name.

// Declares the module and instructs the compiler to look for its contents
mod parser; 

For the declaration mod parser;, Rust will look for the implementation in one of two locations relative to the declaring file:

parser.rs
parser/mod.rs

To extract submodules of parser into their own external files, a directory structure is required. If parser.rs contains the declaration mod ast;, the compiler will look for parser/ast.rs or parser/ast/mod.rs. However, inline submodules (e.g., mod ast { ... }) can be defined directly inside parser.rs without needing a new directory.

Visibility and Privacy Boundaries

By default, all items within a module (functions, structs, fields, methods, and submodules) are private. They are only visible to the module itself and its descendant submodules. The pub keyword modifies this visibility. Rust provides granular visibility modifiers to restrict access to specific scopes:

mod system {
    pub mod security {
        // Private: Accessible only within `security` and its submodules
        fn generate_seed() {}

        // Public: Accessible from anywhere the `security` module is accessible
        pub fn encrypt() {}

        // Crate-level: Accessible anywhere within the current crate
        pub(crate) fn verify_checksum() {}

        // Parent-level: Accessible only to the parent module (`system`)
        pub(super) fn internal_audit() {}

        // Path-level: Accessible only within the specified ancestor path
        pub(in crate::system) fn share_key() {}
    }
}

pub(in path) Semantic Rule: The path specified in a pub(in path) visibility modifier must be an ancestor module of the module where the item is defined.
Struct Field Visibility: Making a struct public (pub struct) does not automatically make its fields public. Fields must be individually marked with pub.

Path Resolution and Scope Import

To reference items across the module tree, Rust uses paths separated by the double colon ::. Paths can be absolute or relative.

crate:: initiates an absolute path from the crate root.
super:: initiates a relative path from the parent module.
self:: initiates a relative path from the current module.

The use keyword binds a full path to a local name, bringing the item into the current module’s scope to reduce verbosity.

mod server {
    pub mod router {
        pub fn dispatch() {}
    }
}

mod client {
    // Absolute path import
    use crate::server::router;
    
    // Relative path import using `super`
    use super::server::router::dispatch;

    fn handle_request() {
        // Accessed via the imported module path
        router::dispatch();
        
        // Accessed via the directly imported function
        dispatch();
    }
}

Re-exporting (`pub use`)

Modules can re-export items from other modules using pub use. This flattens the public API, allowing external consumers to access deeply nested items as if they were defined in the re-exporting module.

mod internal {
    pub mod deep {
        pub struct Configuration;
    }
}

// Re-exports `Configuration` at the root of this module
pub use internal::deep::Configuration;

Tired of Poor Rust Skills? Fix That With Deep Grasping!Learn More

Functions

Traits

Closures

Generics

Enums

Pattern Matching

Structs

Macros

Lifetimes

Error Handling

Variables

Control Flow

Loops

Modules

Compound Types

Collection Types

Numeric Types

Text & Boolean Types

Attributes

Comments

Assignment Operators

Arithmetic Operators

Comparison Operators

Logical Operators

Unary Operators

Reference Operators

Access & Path Operators

Range Operators

Bitwise Operators

Type Cast Operators

Inline Module Declaration

File System Mapping

Visibility and Privacy Boundaries

Path Resolution and Scope Import

Re-exporting (`pub use`)

​Inline Module Declaration

​File System Mapping

​Visibility and Privacy Boundaries

​Path Resolution and Scope Import

​Re-exporting (pub use)

Inline Module Declaration

File System Mapping

Visibility and Privacy Boundaries

Path Resolution and Scope Import

Re-exporting (`pub use`)