Understanding Rust Modules with main.rs and lib.rs

By the end of this page, you will understand that src/main.rs and src/lib.rs define two different crate roots in Rust. You will see why crate::foo fails inside code compiled as part of the binary crate, how module declarations are local to each crate, and how to structure shared code so both your binary and library work correctly.

In Rust, a package can contain multiple crates. The most common case is:

• src/main.rs → a binary crate
• src/lib.rs → a library crate

Even though both files live in the same package, they are not the same crate.

That is the key idea.

What crate means

Inside Rust code, crate:: always refers to the root of the current crate.

So:

• in main.rs, crate means the binary crate rooted at main.rs
• in lib.rs, crate means the library crate rooted at lib.rs

These roots are separate.

Why your code fails

Your main.rs contains:

mod bar;

That means the binary crate includes a module named bar from .

Think of main.rs and lib.rs as two separate buildings, each with its own front door and room map.

• main.rs is one building
• lib.rs is another building

A module declaration like mod bar; adds a room to the building you are currently in.

So if you write mod bar; in main.rs, that creates bar inside the main building. If you write pub mod foo; in lib.rs, that creates foo inside the library building.

Now imagine code in bar.rs says:

Go to the room foo in this building.

That is what crate::foo means.

If bar.rs is being used by the binary crate, then crate means the main building. If the main building does not have a room, the lookup fails.

Core syntax

Declaring modules in a crate root

// src/lib.rs
pub mod foo;
pub mod bar;

This tells Rust that the library crate contains modules from src/foo.rs and src/bar.rs.

// src/main.rs
mod bar;

This tells Rust that the binary crate contains a module from src/bar.rs.

These declarations are independent.

Example 1: Why your current setup fails

// src/main.rs
mod bar;

fn main() {
    println!("Hello");
}

// src/bar.rs
use crate::foo;

This fails because the current crate is the binary crate, and its root only declares bar, not foo.

Consider this working version:

// src/lib.rs
pub mod foo;
pub mod bar;

// src/foo.rs
pub fn say_foo() {
    println!("foo");
}

// src/bar.rs
use crate::foo;

pub fn bar() {
    foo::say_foo();
}

// src/main.rs
fn main() {
    hello_world::bar::bar();
}

Step-by-step

1. Cargo builds the library crate

Rust starts from src/lib.rs.

It sees:

pub mod foo;
pub mod bar;

1. Command-line applications

A common Rust CLI structure is:

• lib.rs contains parsing logic, validation, helpers, and business rules
• main.rs handles argument reading and starts execution

This keeps the app easier to test.

2. Web servers and APIs

In a web app, you might place these in the library crate:

• route handlers
• models
• validation
• database logic

Then main.rs just bootstraps the server.

3. Shared logic across multiple binaries

A package can have several binaries in src/bin/ that all use the same lib.rs.

That is only practical if you understand that the library crate is separate and reusable.

4. Testing

Library code is easier to test because it is designed to be imported.

For example:

// src/lib.rs
pub mod math;

// tests/math_test.rs
use hello_world::math;

#[test]
 () {
    (math::(, ), );
}

In real Rust projects, developers usually avoid duplicating module declarations across main.rs and lib.rs unless they truly want separate implementations.

Common pattern: thin main.rs

A very common layout is:

// src/main.rs
fn main() {
    my_crate::run();
}

// src/lib.rs
pub mod config;
pub mod app;

pub fn run() {
    // orchestrate program logic
}

This has several benefits:

• shared code lives in one place
• tests can target library functions
• binaries stay simple
• module paths are easier to reason about

Visibility patterns

Developers often use:

• pub mod x; when exposing a module from the library root
• mod x; when the module is internal only
• pub fn for functions that must be accessible from other modules or crates

1. Assuming lib.rs and main.rs share one module tree

They do not.

Broken assumption:

// main.rs
mod bar;

// bar.rs
use crate::foo;

// lib.rs
pub mod foo;

Why it breaks:

• bar.rs is compiled under the binary crate
• foo only exists in the library crate

How to avoid it:

• either declare foo in main.rs too
• or, better, move shared modules to lib.rs and use them from main.rs

2. Forgetting pub

Broken code:

// bar.rs
fn () {
    
}

Core rule

main.rs and lib.rs are separate crate roots.

What crate:: means

crate::something

Means: start from the root of the current crate.

Module declaration

mod foo;

• declares foo in the current crate
• usually loads code from foo.rs or foo/mod.rs

pub mod foo;

• same as mod foo;
• also makes the module public

Importing

use crate::foo;

• only works if foo exists in the current crate root

Binary crate pattern

Why does crate::foo fail even though foo exists in lib.rs?

Because crate:: refers to the current crate only. If bar.rs is compiled from main.rs, then crate means the binary crate, not the library crate.

Does lib.rs automatically expose modules to main.rs?

No. lib.rs defines the library crate's module tree. main.rs is a separate binary crate.

Why did adding mod foo; to main.rs fix the problem?

Because it created foo inside the binary crate, so crate::foo became valid there.

What is the best way to organize code when I have both main.rs and lib.rs?

Usually, put reusable logic in lib.rs and keep as a small entry point that calls into the library.

• Rust crates — Modules live inside crates, so crate boundaries explain this issue.
• Rust visibility (pub) — Accessing functions across modules requires correct visibility.
• Rust mod vs use — These are often confused, but they solve different problems.
• Rust paths and crate:: — Understanding path resolution is essential for module lookup.
• Binary crate vs library crate — This is the exact distinction behind main.rs and lib.rs.
• Rust project structure — File layout and module declarations work together.
• Integration tests in Rust — Tests often import the library crate by name, which reinforces crate boundaries.