Rustup vs Cargo: What Each Tool Does and When to Use ThemRust’s tooling ecosystem is one of its strengths. Two core tools—rustup and cargo—are often mentioned together by beginners and experienced developers alike, yet they serve different purposes. This article explains what each tool does, how they interact, and practical guidance on when to use each one. Examples and workflows are included so you can pick the right tool for the job.
Quick summary (one-line)
rustup manages Rust toolchains and components; cargo builds, tests, and packages Rust projects.
What is rustup?
Rustup is the official Rust toolchain installer and manager. It simplifies installing and switching between Rust releases (toolchains) and managing associated components like rustc (the compiler), rust-std (standard library for different targets), rustfmt, and clippy.
Key responsibilities:
- Install and update Rust toolchains (stable, beta, nightly).
- Switch the active toolchain globally or per-directory (overrides).
- Add/remove components and targets (e.g., cross-compilation targets).
- Manage toolchain profiles (minimal, default, complete).
Common commands:
- rustup install stable — installs the stable toolchain.
- rustup default nightly — sets the default toolchain to nightly.
- rustup override set stable — makes the current directory use stable.
- rustup component add clippy — installs Clippy for the active toolchain.
- rustup target add wasm32-unknown-unknown — adds a compilation target.
When to use rustup:
- First-time Rust setup on a machine.
- Switching between stable, beta, and nightly Rust.
- Installing components (clippy, rustfmt) or cross-compilation targets.
- Pinning a project or CI environment to a specific toolchain.
Practical example:
- You want to try a nightly-only feature for a single project. Run:
- rustup toolchain install nightly
- rustup override set nightly This makes the current directory use nightly while other projects remain on stable.
What is cargo?
Cargo is Rust’s build system, package manager, and a project lifecycle tool. It manages dependencies, compiles code, runs tests and benchmarks, and publishes packages (crates) to crates.io. Cargo works at the project level—its configuration files (Cargo.toml and Cargo.lock) are checked into your repository and define the project’s metadata and dependencies.
Key responsibilities:
- Create new projects (cargo new, cargo init).
- Manage dependencies and resolve versions.
- Build and run projects (cargo build, cargo run).
- Test and benchmark (cargo test, cargo bench).
- Format, lint, and clippy integration via cargo fmt and cargo clippy.
- Package and publish crates (cargo package, cargo publish).
Common commands:
- cargo new myapp — creates a new project.
- cargo build –release — builds optimized artifacts.
- cargo run — builds and runs your project.
- cargo test — runs test suites.
- cargo add serde — add a dependency (requires cargo-edit or using Cargo.toml).
- cargo publish — publish a crate to crates.io.
When to use cargo:
- Everyday development: building, running, and testing code.
- Managing and adding dependencies for a project.
- Creating reproducible builds with Cargo.lock in applications.
- Publishing libraries to crates.io.
Practical example:
- To start a new CLI tool:
- cargo new mycli –bin
- cd mycli
- cargo add clap
- cargo run
How rustup and cargo work together
Rustup and Cargo complement each other. rustup manages the toolchain that provides rustc and other tools; cargo is the project-level tool that invokes rustc and other components to build and manage your project.
Interactions:
- Cargo uses the rustc provided by the active rustup toolchain.
- rustup installs components (like rustfmt/clippy) that cargo subcommands can call (cargo fmt, cargo clippy).
- rustup overrides determine which rustc cargo will invoke in a directory or CI job.
Example workflow:
- rustup default stable
- cargo new demo
- cd demo
- cargo build This builds demo using the rustc that rustup set as stable.
Differences summarized
| Area | rustup | cargo |
|---|---|---|
| Primary role | Toolchain & component manager | Build system & package manager |
| Scope | System- / machine-level (or per-directory overrides) | Project-level (Cargo.toml, Cargo.lock) |
| Installs | rustc, std, components, targets, toolchains | Rust packages (crates) as dependencies for projects |
| Typical commands | rustup install, rustup default, rustup component add | cargo build, cargo run, cargo test, cargo publish |
| Use in CI | Choose and pin toolchain versions | Build, test, run, and publish project artifacts |
Common workflows and recommendations
- Local development with stable Rust:
- rustup default stable
- cargo new / cargo build / cargo test
- Experimenting with nightly features only for a single project:
- rustup toolchain install nightly
- cd project && rustup override set nightly
- cargo +nightly build (or rely on override)
- CI configuration:
- Use rustup to install and pin the toolchain (rustup toolchain install 1.70.0)
- Use cargo to run tests and produce artifacts (cargo test –locked)
- Cross-compilation:
- rustup target add aarch64-unknown-linux-gnu
- Install appropriate linker/toolchain components; use cargo to build for that target.
- Ensuring reproducible builds for an application:
- Check in Cargo.lock; use rustup to pin the compiler version in docs or CI.
Troubleshooting tips
- “cargo: command not found” after installing rustup:
- Ensure rustup added ~/.cargo/bin to your PATH (rustup prints instructions). Restart shell.
- Mismatched toolchain in CI:
- Use rustup toolchain install
and rustup override set in the build script.
- Use rustup toolchain install
- Need clippy or rustfmt:
- rustup component add clippy
- rustup component add rustfmt
- Want to run cargo with a specific toolchain without overrides:
- cargo +nightly build
Advanced notes
- Toolchain profiles: rustup has profiles (minimal, default, complete) to control what’s installed with a toolchain.
- Custom toolchains and components: You can install custom or locally built toolchains via rustup toolchain link.
- cargo subcommands: Cargo supports third-party subcommands (cargo-edit, cargo-watch) that you install as separate binaries and invoke as cargo edit or cargo watch.
- Multiple toolchains side-by-side: rustup allows parallel toolchains so you can test your crate across stable, beta, and nightly easily.
When to choose which tool — practical checklist
- Need to install Rust or change the compiler version? Use rustup.
- Add a linter/formatter component or a compilation target? Use rustup.
- Start a project, add dependencies, build, test, or publish? Use cargo.
- Want to run cargo using a non-default toolchain once? Use cargo +toolchain or rustup override for the directory.
- Setting up CI? Use rustup to install/pin toolchain, cargo to build/test.
Rustup and Cargo are distinct but tightly integrated: rustup shapes which compiler and components are available; cargo uses those to build, test, and manage projects. Understanding both helps you set up robust local environments, predictable CI pipelines, and smooth cross-compilation workflows.
Leave a Reply