How to Split a Rust Module Across Multiple Files

By the end of this page, you will understand how Rust modules map to files and folders, how to split a module into submodules across multiple files, and how to expose types cleanly with pub use so they can be imported from a single module path.

Rust modules are primarily about organizing code and controlling visibility, not just about matching folders on disk.

A common beginner misunderstanding is thinking that one module must be written in one file. In Rust, a module can be declared in one place and its contents can be loaded from other files. This is the normal way to build larger projects.

The key ideas are:

• mod name; declares a module and tells Rust to load it from another file.
• pub mod name; does the same thing, but makes that module public.
• pub use ...; re-exports items so users can access them from a simpler path.
• Files and folders help Rust find module code, but the module tree is what really matters.

For your math example, each file like vector.rs, matrix.rs, and complex.rs is usually its own submodule inside a parent math module.

That means the real structure is not “one module split invisibly across files,” but rather:

• a parent module: math
• child modules: math::vector, math::matrix, math::complex

Then, if you want , you can from the parent module.

Think of a Rust module like a folder with a front desk.

• The folder contains smaller rooms: vector, matrix, complex
• Each room has its own file
• The front desk is the parent math module
• The front desk can either:
  • tell visitors to go into a room directly: math::vector::Vector
  • hand visitors the item directly: math::Vector using pub use

So the parent module is not forced to contain all the code itself. It can simply coordinate and expose things from its child modules.

The most common way to structure this in Rust is:

src/
  main.rs
  math/
    mod.rs
    vector.rs
    matrix.rs
    complex.rs

main.rs

mod math;

use math::Vector;

fn main() {
    let v = Vector { x: 3.0, y: 4.0 };
    println!("({}, {})", v.x, v.y);
}

math/mod.rs

pub mod vector;
pub mod matrix;
pub mod complex;

pub use vector::Vector;
pub use matrix::Matrix;
pub use complex::Complex;

math/vector.rs

pub struct Vector {
     x: ,
     y: ,
}

Consider this example:

// main.rs
mod math;
use math::Vector;

fn main() {
    let v = Vector { x: 1.0, y: 2.0 };
    println!("{} {}", v.x, v.y);
}

// math.rs or math/mod.rs
pub mod vector;
pub use vector::Vector;

// math/vector.rs
pub struct Vector {
    pub x: f64,
    pub y: f64,
}

Step by step

1. Rust starts compiling main.rs.
2. It sees mod math;.
3. Rust looks for the math module in either:
   • src/math.rs, or
   • src/math/mod.rs

Splitting modules across files is extremely common in real Rust projects.

1. Domain models

A project may group related types together:

user/
  profile.rs
  settings.rs
  permissions.rs

This keeps each type focused and easier to maintain.

2. API clients

An HTTP client crate might organize code by API area:

api/
  users.rs
  payments.rs
  invoices.rs

The parent module can re-export the most important public types.

3. Math or graphics libraries

Types like vectors, matrices, colors, transforms, and quaternions are often split into separate files but grouped under one module tree.

4. Compiler or parser code

Larger tools often have modules such as:

ast/
  expr.rs
  stmt.rs
  types.rs

Each file handles one part of the language model.

5. Internal application organization

Even non-library applications use modules to keep code readable, testable, and easier to navigate.

In real projects, developers usually combine submodules with carefully chosen public exports.

Common pattern: internal structure, simple public API

pub mod vector;
pub mod matrix;

pub use vector::Vector;
pub use matrix::Matrix;

This gives you:

• internal organization: math::vector, math::matrix
• simple external usage: math::Vector, math::Matrix

Pattern: hide implementation details

Sometimes the child modules are not made public:

mod vector;
mod matrix;

pub use vector::Vector;
pub use matrix::Matrix;

Now users can access math::Vector, but not math::vector::... directly. This is useful when you want a cleaner API surface.

Pattern: grouped responsibilities

1. Thinking multiple files automatically become one module

Each file is usually a separate module unless declared otherwise.

Broken expectation:

math/
  vector.rs
  matrix.rs

Rust does not automatically combine those into one math module by name alone. You still need a parent module file.

2. Forgetting to declare child modules

If math.rs does not declare mod vector;, Rust will not load vector.rs.

Broken example:

// math.rs
pub use vector::Vector;

This fails because vector was never declared.

Correct version:

mod vector;
pub use vector::Vector;

3. Forgetting pub

A type may exist but still be inaccessible.

Broken example:

// main.rs
mod math;
use math::Vector;

// math.rs or math/mod.rs
mod vector;
pub use vector::Vector;

// math/vector.rs
pub struct Vector {
    pub x: f64,
    pub y: f64,
}

Rules to remember

• mod name; tells Rust to load a module from a file.
• A parent module must declare its child modules.
• use does not create modules; it only imports names.
• pub controls visibility.
• pub use re-exports names from one module level to another.
• Files are usually lowercase: vector.rs, not Vector.rs.

Common layouts

src/
  main.rs
  math.rs
  math/
    vector.rs

Can a Rust module be split across multiple files?

Yes. This is a normal and idiomatic way to organize Rust code. Usually, a parent module declares child modules stored in separate files.

Why doesn't Rust automatically combine files in a folder into one module?

Rust requires explicit module declarations so the module tree is clear and visibility is controlled intentionally.

Should I use mod.rs or math.rs?

Both are valid. Many newer codebases prefer math.rs plus a math/ folder, but mod.rs is still completely acceptable.

How do I make use math::Vector; work?

Re-export the type from the parent module:

pub use vector::Vector;

What is the difference between mod and use in Rust?

mod declares a module. use imports a name from an existing module path into the current scope.

Do I need pub mod vector; or just mod vector;?

• mod declaration — the core mechanism for defining modules and loading them from files.
• use imports — needed to bring module paths or types into scope.
• visibility with pub — controls what code is accessible outside a module.
• re-exports with pub use — lets you expose items from simpler paths.
• crate root — helps explain where module paths begin in a binary or library crate.
• paths and namespaces — important for understanding names like math::vector::Vector.
• pub(crate) visibility — useful when organizing larger internal codebases.
• Rust file and module conventions — explains lowercase file names and standard layouts.