Cargo is Rust’s official package manager and build system. If you are learning Rust, Cargo is one of the most important tools you will use.
Instead of manually compiling every Rust file and managing external libraries yourself, Cargo handles most of the work for you.
With Cargo, you can:
- Create Rust projects
- Build projects
- Run applications
- Manage dependencies
- Check code for compilation errors
- Run tests
- Generate documentation
- Create optimized release builds
- Install Rust command-line tools
- Publish Rust packages
This guide explains how Cargo works and covers the most useful Cargo commands for beginners.
What Is Cargo in Rust?
Cargo is the standard package manager and build tool used by Rust projects.
It handles three major tasks:
Project Management
Dependency Management
Build Management
For example, without Cargo you can compile a simple Rust file manually:
rustc main.rs
This is fine for very small programs.
However, real applications usually contain:
Multiple Rust files
External packages
Tests
Configuration
Build settings
Different development and release builds
Cargo manages these things using a standardized Rust project structure.
Check Whether Cargo Is Installed
If you installed Rust using rustup, Cargo is normally installed with Rust.
Open your terminal and run:
cargo --version
You should see output similar to:
cargo 1.x.x
You can also check Rust:
rustc --version
If both commands return version information, your Rust development environment is ready.
Create Your First Cargo Project
The easiest way to create a Rust project is:
cargo new hello_rust
Cargo creates a new directory:
hello_rust/
Move inside it:
cd hello_rust
Your project will have a structure similar to:
hello_rust/
├── Cargo.toml
└── src/
└── main.rs
This is the basic structure of a Rust binary project.
Understanding the Cargo Project Structure
Let’s understand the two most important parts.
src/main.rs
This contains the application’s Rust source code.
Cargo automatically creates:
fn main() {
println!("Hello, world!");
}
The main() function is the starting point of a binary Rust application.
Cargo.toml
Cargo.toml is the manifest file for your Rust project.
A basic file looks similar to:
[package]
name = "hello_rust"
version = "0.1.0"
edition = "2024"[dependencies]
The exact edition generated depends on your installed Cargo/Rust toolchain and project configuration.
The file contains important project information and configuration.
Understanding Cargo.toml
Let’s break it down.
[package]
The [package] section contains information about your package.
[package]
name = "hello_rust"
version = "0.1.0"
edition = "2024"
name
Defines the package name.
name = "hello_rust"
version
Defines your project’s version.
version = "0.1.0"
Rust packages generally use semantic versioning:
MAJOR.MINOR.PATCH
For example:
1.0.0
1.1.0
1.1.1
2.0.0
edition
Defines which Rust edition the project uses.
For example:
edition = "2024"
Rust editions allow the language to evolve while maintaining compatibility between projects.
What Is the [dependencies] Section?
External Rust packages used by your project are usually listed under:
[dependencies]
For example:
[dependencies]
serde = "1.0"
Cargo reads this configuration, resolves the dependency and its required dependencies, downloads the packages, and includes them when building your project.
What Is a Crate?
You will frequently see the word crate when working with Cargo.
A crate is a Rust compilation unit.
Rust projects commonly work with two main types.
Binary Crate
A binary crate creates an executable program.
It normally contains:
src/main.rs
For example:
fn main() {
println!("Hello Rust");
}
Applications and command-line programs are common examples of binary crates.
Library Crate
A library crate contains reusable functionality that other Rust programs can use.
Its main source file is usually:
src/lib.rs
Package vs Crate
Beginners often confuse packages and crates.
A crate is a compilation unit.
A package is a collection managed by Cargo and described by a Cargo.toml manifest.
A package can contain multiple targets, such as a library and one or more binaries.
For beginner projects, you will usually work with one package containing a single binary.
Run a Rust Project with Cargo
Use:
cargo run
Cargo will compile the project and then run it.
For the default project:
Hello, world!
You do not need to manually run:
rustc src/main.rs
Cargo manages the compilation process for you.
What Happens When You Run cargo run?
When you execute:
cargo run
Cargo roughly performs:
Read Cargo.toml
↓
Resolve dependencies
↓
Compile required code
↓
Build the application
↓
Run the executable
If nothing relevant has changed since the previous build, Cargo can reuse existing build artifacts instead of rebuilding everything unnecessarily.
Build a Rust Project
If you only want to compile the project without running it, use:
cargo build
Cargo builds the project in development mode.
Generated build files are stored under:
target/
For a typical binary project, the development executable is placed under:
target/debug/
cargo build vs cargo run
These commands have different purposes.
cargo build
cargo build
Compiles the application.
It does not automatically run it.
cargo run
cargo run
Builds the application when necessary and then runs it.
Therefore:
cargo build → Compile
cargo run → Compile + Run
During normal development, you may use cargo run frequently.
Check Rust Code Without Building the Final Executable
Cargo provides:
cargo check
This checks whether your project can compile without producing the final executable.
For example:
cargo check
This is especially useful while developing because it can be faster than performing a complete build.
A common development workflow is:
Write code
↓
cargo check
↓
Fix errors
↓
cargo run
cargo check vs cargo build
cargo check
cargo check
Checks whether the project compiles.
cargo build
cargo build
Compiles the project and produces build artifacts.
Use cargo check when you mainly want quick feedback about compilation errors.
Use cargo build when you need the compiled program.
Build an Optimized Release Version
During development:
cargo build
creates a development build.
For an optimized production build, use:
cargo build --release
Cargo stores release artifacts under:
target/release/
Release builds enable optimizations and normally take longer to compile.
Use:
cargo build
while developing and:
cargo build --release
when you need an optimized executable.
Running in Release Mode
You can also build and immediately run the optimized version:
cargo run --release
This is useful when testing application performance in release mode.
Adding Dependencies with Cargo
One of Cargo’s most important jobs is dependency management.
Suppose your project needs the rand crate.
You can add it using:
cargo add rand
Cargo updates your Cargo.toml.
It will contain something similar to:
[dependencies]
rand = "..."
The exact version depends on the version selected when the command is executed.
You can then use the dependency in your Rust code according to that crate’s API.
Adding Dependencies Manually
Dependencies can also be added manually to Cargo.toml.
For example:
[dependencies]
serde = "1.0"
After saving the file, Cargo will resolve and download the dependency when required by commands such as:
cargo build
or:
cargo run
Where Do Rust Packages Come From?
The primary public package registry for Rust is:
crates.io
Cargo can download packages published there.
Rust packages available through the registry are commonly called crates.
You can search for packages from the command line using:
cargo search serde
Cargo can then show matching crates.
What Is Cargo.lock?
After Cargo resolves dependencies, you will normally see:
Cargo.lock
Your project may now look like:
hello_rust/
├── Cargo.lock
├── Cargo.toml
├── src/
│ └── main.rs
└── target/
Cargo.lock records the exact dependency versions selected for the build.
For example, your Cargo.toml might allow a compatible range of versions, while Cargo.lock records the specific versions Cargo resolved.
This helps create reproducible builds.
Cargo.toml vs Cargo.lock
These two files serve different purposes.
Cargo.toml
Describes what your project requires.
Example:
[dependencies]
serde = "1.0"
Cargo.lock
Records the exact dependency resolution used by Cargo.
A simple way to remember the difference is:
Cargo.toml
↓
Dependency requirements
Cargo.lock
↓
Resolved dependency versions
You generally should not manually edit Cargo.lock.
Cargo manages it automatically.
Updating Dependencies
Cargo provides:
cargo update
This updates dependencies recorded in the lock file while respecting the version requirements specified in Cargo.toml.
For example:
cargo update
Cargo recalculates compatible dependency versions and updates Cargo.lock where appropriate.
Removing a Dependency
You can remove a dependency using:
cargo remove rand
Cargo removes it from the manifest.
You can also edit Cargo.toml manually, but cargo remove is convenient.
View the Dependency Tree
As projects grow, dependencies can depend on other dependencies.
You can inspect this using:
cargo tree
The output may conceptually look like:
my_project
├── dependency_a
│ └── dependency_c
└── dependency_b
This is useful when investigating:
- Dependency versions
- Duplicate dependencies
- Transitive dependencies
- Dependency conflicts
Cleaning Cargo Build Files
Cargo stores generated build files inside:
target/
These files can consume significant disk space over time.
To remove generated build artifacts, use:
cargo clean
After running it, Cargo removes generated artifacts for the project.
The next build will compile everything again as needed.
Run Tests with Cargo
Cargo includes built-in support for running Rust tests.
Use:
cargo test
Example:
fn add(a: i32, b: i32) -> i32 {
a + b
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_add() {
assert_eq!(add(2, 3), 5);
}
}
Run:
cargo test
Cargo compiles and executes the project’s applicable tests.
This can include unit tests, integration tests, and documentation tests depending on the project.
Generate Rust Documentation
Cargo can generate documentation for your project:
cargo doc
The generated documentation is stored in the project’s build output.
A particularly useful command is:
cargo doc --open
This generates the documentation and opens it in your browser.
Create a Project in an Existing Directory
cargo new creates a new directory.
But sometimes you already have a directory.
For example:
mkdir my_project
cd my_project
You can initialize Cargo inside it using:
cargo init
Cargo creates the required project files.
cargo new vs cargo init
cargo new
cargo new my_project
Creates a new directory and initializes a Cargo project.
cargo init
cargo init
Initializes a Cargo project inside an existing directory.
Remember:
New folder + project → cargo new
Existing folder → cargo init
Create a Library Project
You can explicitly create a library package using:
cargo new my_library --lib
The project structure will typically contain:
my_library/
├── Cargo.toml
└── src/
└── lib.rs
Instead of:
src/main.rs
you get:
src/lib.rs
because the project is designed as a library.
Installing Rust CLI Tools with Cargo
Cargo can install binary crates from a registry.
The basic command is:
cargo install package_name
For example:
cargo install ripgrep
Cargo downloads, compiles, and installs the binary.
Installed Cargo binaries are commonly placed in:
$CARGO_HOME/bin
which is typically:
~/.cargo/bin
unless the Cargo home directory has been changed.
Uninstalling Cargo-Installed Tools
Use:
cargo uninstall package_name
For example:
cargo uninstall ripgrep
This removes a binary installed using Cargo.
Passing Arguments with cargo run
Suppose your Rust application expects command-line arguments.
Cargo lets you pass arguments after:
--
Example:
cargo run -- hello
Cargo interprets arguments before -- as Cargo options.
Arguments after -- are passed to your Rust application.
For example:
cargo run -- user.json
passes user.json to your program.
Cargo Help
If you forget how a Cargo command works, use:
cargo help
For help with a specific command:
cargo help build
You can also use:
cargo build --help
or:
cargo run --help
This is extremely useful when learning Cargo.
Useful Cargo Commands for Beginners
Here are the commands worth remembering first.
| Command | Purpose |
|---|---|
cargo --version | Check Cargo version |
cargo new project_name | Create a new project |
cargo init | Initialize an existing directory |
cargo build | Build project |
cargo run | Build and run project |
cargo check | Check code for compile errors |
cargo build --release | Create optimized build |
cargo run --release | Run optimized build |
cargo test | Run tests |
cargo add crate_name | Add dependency |
cargo remove crate_name | Remove dependency |
cargo update | Update resolved dependencies |
cargo tree | Show dependency tree |
cargo clean | Remove generated build artifacts |
cargo doc | Generate documentation |
cargo doc --open | Generate and open documentation |
cargo search name | Search registry packages |
cargo install crate_name | Install binary crate |
cargo uninstall crate_name | Remove installed binary |
cargo help | Display Cargo help |
Typical Cargo Development Workflow
A beginner’s Rust workflow might look like this.
Step 1: Create Project
cargo new calculator
Step 2: Enter Project
cd calculator
Step 3: Write Code
Edit:
src/main.rs
For example:
fn main() {
let a = 10;
let b = 20;
println!("Result: {}", a + b);
}
Step 4: Check Code
cargo check
Step 5: Run Project
cargo run
Output:
Result: 30
Step 6: Run Tests
cargo test
Step 7: Create Release Build
When the application is ready:
cargo build --release
This creates the optimized build under:
target/release/
Common Cargo Errors
Beginners may encounter a few common problems.
cargo: command not found
If your terminal says:
cargo: command not found
Cargo may not be installed or its binary directory may not be available in your system’s PATH.
If you installed Rust through rustup, reopening the terminal after installation may be necessary.
Check:
cargo --version
Could Not Find Cargo.toml
You may see an error indicating that Cargo cannot find:
Cargo.toml
This commonly happens when you run a Cargo project command from the wrong directory.
Move into your project:
cd my_project
Then run:
cargo run
Dependency Build Error
Sometimes an external crate fails to compile.
Useful first steps include:
cargo check
and inspecting the actual compiler error.
You can also inspect dependencies using:
cargo tree
Do not automatically delete project files whenever a dependency error appears; first identify the actual cause from Cargo’s error output.
Cargo vs rustc
rustc is the Rust compiler.
Cargo is the higher-level project and package management tool that invokes the compiler as part of the build process.
For a simple file:
rustc main.rs
can be enough.
For normal Rust projects:
cargo build
is usually more convenient.
Cargo additionally handles:
- Dependencies
- Project structure
- Build configuration
- Testing
- Documentation
- Release profiles
- Package management
A simple way to understand them is:
rustc → Rust compiler
Cargo → Project + dependency + build management
Why Is Cargo Important?
Cargo provides a consistent workflow across Rust projects.
Once you understand commands such as:
cargo new
cargo check
cargo build
cargo run
cargo test
you already know the basic workflow for working with many Rust projects.
It also eliminates much of the manual work involved in finding, downloading, compiling, and linking external dependencies.
Cargo Beginner Cheat Sheet
# Check Cargo
cargo --version
# Create project
cargo new my_project
# Initialize existing directory
cargo init
# Check project
cargo check
# Build project
cargo build
# Run project
cargo run
# Build optimized version
cargo build --release
# Run optimized version
cargo run --release
# Add dependency
cargo add crate_name
# Remove dependency
cargo remove crate_name
# Update dependencies
cargo update
# View dependency tree
cargo tree
# Run tests
cargo test
# Generate documentation
cargo doc
# Generate and open documentation
cargo doc --open
# Clean generated files
cargo clean
# Search for crates
cargo search crate_name
# Install CLI package
cargo install crate_name
# Uninstall CLI package
cargo uninstall crate_name
# Get help
cargo help
Final Thoughts
Cargo is an essential part of Rust development.
It combines several important development tasks into one tool:
Create projects
+
Build code
+
Run applications
+
Manage dependencies
+
Run tests
+
Generate documentation
+
Create release builds
For beginners, you do not need to learn every Cargo feature immediately.
Start with these five commands:
cargo new
cargo check
cargo build
cargo run
cargo test
Then learn dependency management:
cargo add
cargo remove
cargo update
Finally, when your application is ready for an optimized build, use:
cargo build --release
Once you are comfortable with Cargo.toml, Cargo.lock, dependencies, and these core commands, you will be able to manage most beginner and intermediate Rust projects confidently.
