Rust mod.rs Files: Purpose, Modules, and Modern Alternatives

You will learn how Rust organizes modules across files and directories, why mod.rs was historically used as a directory module's entry file, and why modern Rust code usually uses module_name.rs instead. You will also see how to declare child modules and control their visibility.

Rust uses a module system to organize code into namespaces and files. A module can contain functions, structs, constants, submodules, and visibility rules.

A mod.rs file is the traditional file that represents a module stored in a directory. For example, this layout:

src/
├── network/
│   ├── mod.rs
│   ├── client.rs
│   └── server.rs
└── main.rs

can be connected from main.rs like this:

mod network;

Rust reads src/network/mod.rs as the contents of the network module. That file can then declare its child modules:

mod client;
mod server;

Historically, mod.rs was required when a module had its own directory. Since Rust 2018, Rust also supports the more direct layout below:

src/
├── network.rs
└── network/
    ├── client.rs
    └── server.rs

// src/network.rs
mod client;
mod server;

This modern style is generally preferred because network.rs clearly names the network module. A mod.rs file is still valid Rust, so you will often encounter it in older projects or projects that retain the older convention.

Think of a module as a labeled folder in a filing cabinet.

• network is the folder label.
• network.rs or network/mod.rs is the folder's index page.
• client.rs and server.rs are documents inside that folder.

The index page decides which documents belong to the folder by declaring them with mod client; and mod server;.

Both network.rs and network/mod.rs can serve as the index page. The modern style puts the module name in the filename; the older style uses the generic name mod.rs inside the module directory.

A module declaration uses the mod keyword:

mod helpers;

If Rust finds this declaration in src/main.rs, it looks for one of these files:

src/helpers.rs
src/helpers/mod.rs

Modern directory module layout

src/
├── main.rs
├── helpers.rs
└── helpers/
    └── text.rs

// src/main.rs
mod helpers;

fn main() {
    println!("{}", helpers::text::shout("hello"));
}

// src/helpers.rs
pub mod text;

// src/helpers/text.rs
pub fn shout(message: &str) -> String {
    message.to_uppercase()
}

pub mod text; both declares the text child module and makes it accessible from outside helpers. pub fn shout makes the function accessible from outside text.

Equivalent traditional mod.rs layout

src/
├── main.rs
└── helpers/
    ├── mod.rs
    └── text.rs

// src/helpers/mod.rs
pub mod text;

The main.rs and text.rs code can stay exactly the same. Only the location of the parent module's source file changed.

Consider this project:

src/
├── main.rs
├── math.rs
└── math/
    └── add.rs

// src/main.rs
mod math;

fn main() {
    let total = math::add::two(4);
    println!("{total}");
}

// src/math.rs
pub mod add;

// src/math/add.rs
pub fn two(value: i32) -> i32 {
    value + 2
}

Execution and compilation proceed as follows:

1. Rust starts with main.rs, the crate root for a binary crate.
2. mod math; tells Rust to load the math module from math.rs or math/mod.rs.
3. Rust loads math.rs.
4. pub mod add; tells Rust to load math/add.rs or math/add/mod.rs and exposes add through math.
5. Rust loads math/add.rs.
6. main calls math::add::two(4).
7. two returns 6, so the program prints 6.

If math.rs were replaced with math/mod.rs, the module path math::add::two and program output would be unchanged.

Modules and directory modules are useful when one feature grows beyond a single source file.

• HTTP client: Put request construction, authentication, and response parsing under an api module.
• Command-line application: Place each command in modules such as commands::build, commands::test, and commands::clean.
• Web server: Group routes, middleware, database code, and application state into separate modules.
• Game or simulation: Keep physics, rendering, input, and world-state code in separate modules.
• Library crate: Expose a small public API from a parent module while keeping implementation details in private child modules.

For example, a library might use this structure:

src/
├── lib.rs
├── parser.rs
└── parser/
    ├── lexer.rs
    └── tokens.rs

The parser.rs file can expose only the types users need while keeping lower-level parsing helpers private.

In real Rust projects, a parent module file commonly acts as an API boundary. It declares child modules, chooses what is public, and may re-export convenient names.

// src/api.rs
mod internal_client;
pub mod types;

pub use internal_client::Client;

Here:

• internal_client is private to api.
• types is public, so callers can use crate::api::types.
• Client is re-exported, so callers can write crate::api::Client instead of knowing its implementation module.

A typical project may also use private modules to prevent accidental coupling:

// src/config.rs
mod file_format;

pub fn load() -> Result<AppConfig, ConfigError> {
    file_format::read_config()
}

Code outside config cannot call file_format::read_config() directly. It must use the intentionally designed config::load() function.

Use a directory module when a module has multiple related files. Keep a small module in one name.rs file until splitting it improves readability.

Expecting a folder to create a module automatically

Creating src/tools/format.rs is not enough. Rust needs a parent module declaration.

// src/main.rs
mod tools;

Then Rust needs either src/tools.rs or src/tools/mod.rs, containing:

pub mod format;

Declaring a child module in the wrong file

This is incorrect if format.rs is inside the tools directory:

// src/main.rs
mod format; // Rust searches for src/format.rs, not src/tools/format.rs

Declare mod format; in tools.rs or tools/mod.rs instead.

Forgetting pub

The following compiles, but format cannot be accessed from outside tools:

// src/tools.rs
mod format;

Use pub mod format; if external code should access it.

Similarly, a public module does not make every item inside it public:

pub mod format {
    fn run() {} // Still private
}

Use pub fn run() when callers need the function.

Using both tools.rs and tools/mod.rs

Do not create both files for the same tools module. mod tools; would have two possible source files, which causes a compiler error. Choose one layout.

Adding mod for a module declared inline

An inline module already has its body in the same file:

mod tools {
    pub fn run() {}
}

Do not also create tools.rs for that same declaration unless you change the declaration to the file-based form mod tools;.

mod versus use

mod helpers;                 // Loads this crate's helpers module.
use crate::helpers::text;    // Makes `text` available in this scope.

mod.rs versus lib.rs and main.rs

• main.rs is normally the root module of a binary crate.
• lib.rs is normally the root module of a library crate.
• mod.rs is a traditional file for a non-root module represented by a directory.
• name.rs is the modern preferred filename for that same non-root module.

// Declare a file-based child module.
mod tools;

// Make a child module accessible from the parent module's users.
pub mod format;

// Make an item accessible outside its module.
pub fn run() {}

// Import an existing path into scope.
use crate::tools::format;

• mod tools; loads one of:
  • tools.rs
  • tools/mod.rs
• Use tools.rs for new directory-based modules in modern Rust.
• Put child files beside a directory module in tools/, such as tools/format.rs.
• A directory by itself is not a Rust module; it needs a parent module file and a mod declaration.
• mod declares or loads a module; use imports a name for convenient access.
• Modules and their contents are private by default. Add pub deliberately.
• Never keep both tools.rs and tools/mod.rs for the same module.

Is mod.rs required in Rust?

No. It is still supported, but Rust 2018 introduced the preferred alternative of using module_name.rs as the parent module file.

When should I use mod.rs?

Usually, use it only when following an existing project's convention or working in an older codebase. For new code, prefer module_name.rs.

What replaces mod.rs in modern Rust?

For a network module, use src/network.rs. Put its child modules in src/network/, such as src/network/client.rs.

Can I have both foo.rs and foo/mod.rs?

No. Both represent the same foo module for a mod foo; declaration, so Rust reports an ambiguity error.

Does mod foo; make foo public?

No. Modules are private by default. Use pub mod foo; when the parent module's users should access it.

Does a public module make all its functions public?

No. Items also need their own visibility, such as pub fn function_name().

Is mod.rs the crate root?

Usually not. Crate roots are typically main.rs for binary crates and lib.rs for library crates. A mod.rs file traditionally represents a module inside the crate.

• Rust modules — The namespace and code-organization feature that mod.rs represents.
• Crates and crate roots — Explains the role of main.rs and lib.rs as starting modules.
• Visibility with pub — Controls whether modules, functions, and types can be accessed from other modules.
• The use keyword — Imports module paths into the current scope after modules are declared.
• File system module layout — Covers how Rust maps mod name; declarations to source files.
• Re-exports with pub use — Lets a parent module present a cleaner public API.
• Rust 2018 edition — Introduced the modern file layout that makes mod.rs optional.