Skip to content
C Codeloom
Rust

Install Rust and Run Your First Program

A complete walkthrough of installing Rust with rustup on macOS, Linux, and Windows, then creating your first Cargo project and running it from the terminal.

·8 min read · By Yash Kesharwani
Beginner 10 min read

What you'll learn

  • ✓How to install Rust on macOS, Linux, and Windows with rustup
  • ✓What rustc and cargo actually do
  • ✓How to create a new project with cargo new
  • ✓The difference between cargo run, cargo build, and cargo check
  • ✓How a Cargo project is laid out on disk

Prerequisites

This post takes you from a fresh machine to a running Rust program. By the end you will have rustup, rustc, and cargo installed, a project on disk, and a Hello, world! binary you built yourself.

Use rustup, not your package manager

The official installer for Rust is rustup. It manages the toolchain, lets you switch between stable, beta, and nightly, and updates with one command. Do not install Rust from Homebrew, apt, or the Microsoft Store — those packages go stale fast and make life harder when you need to update.

The rules are simple:

  • macOS and Linux: one shell command from rustup.rs.
  • Windows: download rustup-init.exe from the same site.

We will walk through each.

Installing on macOS and Linux

Open a terminal and run:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

The installer asks one question — pick option 1, the default install. It downloads the stable toolchain, installs rustup, rustc, and cargo into ~/.cargo/bin, and updates your shell profile so those binaries are on your PATH.

When it finishes, either open a new terminal or run:

source $HOME/.cargo/env

Then verify:

rustc --version
# output: rustc 1.84.0 (or newer)

cargo --version
# output: cargo 1.84.0 (or newer)

If both commands print a version, you are done.

macOS extra step

On macOS you also need the Xcode command-line tools, which provide the linker Rust uses. If you don’t already have them:

xcode-select --install

A dialog appears; click Install. This takes a few minutes.

Linux extra step

On Debian and Ubuntu, install a C linker and build essentials so Rust can link binaries:

sudo apt update && sudo apt install build-essential

On Fedora or RHEL:

sudo dnf install gcc

On Arch:

sudo pacman -S base-devel

Installing on Windows

Two paths. Pick one.

Recommended: native Windows. Download rustup-init.exe from rustup.rs and run it. The installer will prompt you to install the Visual Studio C++ Build Tools — accept. Rust uses the MSVC linker by default on Windows, and you need those tools for it to work.

When the installer finishes, open a new PowerShell or Command Prompt window and verify:

rustc --version
cargo --version

Alternative: WSL2. If you prefer a Linux workflow on Windows, install WSL2 and Ubuntu, then follow the Linux instructions above inside WSL. This is the right choice if your project will eventually deploy to Linux.

What you just installed

Three binaries matter:

  • rustup — the toolchain manager. Use it to update Rust (rustup update), switch channels (rustup default stable), or add components like the formatter (rustup component add rustfmt).
  • rustc — the compiler itself. You will almost never call it directly. Cargo calls it for you.
  • cargo — the build tool, package manager, test runner, and documentation generator, all in one binary. You will live in cargo.

If you came from Python, cargo plays the role of pip + venv + pytest + setup.py + a build system. If you came from Node, it is npm + webpack + jest + tsc rolled together. It is the best part of the Rust toolchain.

Creating your first project

Pick a directory you don’t mind cluttering. Then run:

cargo new hello
# output: Creating binary (application) `hello` package

This creates a directory called hello with the layout below. Step inside:

cd hello
ls
# output: Cargo.toml  src

Two things. The first is a manifest, the second is your source code.

Cargo.toml

Open Cargo.toml. It looks like this:

[package]
name = "hello"
version = "0.1.0"
edition = "2021"

[dependencies]
  • [package] lists metadata about your crate (Rust calls a package a crate).
  • edition pins the language edition. Editions are how Rust evolves without breaking old code; 2021 is the current default, with 2024 rolling out.
  • [dependencies] is where you add libraries from crates.io. Empty for now.

src/main.rs

Open src/main.rs:

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

This is the entry point of your binary. cargo new generated it for you, identical to the program from What Is Rust?.

Running the program

From inside the hello directory:

cargo run
# output:
#    Compiling hello v0.1.0 (/Users/you/hello)
#     Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.42s
#      Running `target/debug/hello`
# Hello, world!

What just happened, in order:

  1. Cargo read Cargo.toml to figure out what to build.
  2. It invoked rustc to compile src/main.rs into a binary at target/debug/hello.
  3. It executed that binary, which printed Hello, world!.

Run it again:

cargo run
# output:
#     Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.01s
#      Running `target/debug/hello`
# Hello, world!

This time there is no compile step — nothing changed, so cargo reuses the existing binary. The cache lives in target/.

cargo build vs cargo run vs cargo check

Three commands you will reach for constantly.

cargo build compiles your code into a binary at target/debug/<name> but does not run it. Use this when you want to ship the binary, or when you are about to run it many times in a row.

cargo build
./target/debug/hello
# output: Hello, world!

cargo run does cargo build and then runs the binary. Use this during development.

cargo check does only the type-checking and borrow-checking parts of compilation — it never produces a binary, and is significantly faster than cargo build. Most experienced Rust developers run it constantly while editing.

Debug vs release builds

By default, cargo builds in debug mode: fast to compile, slow to run, with debugging symbols and integer overflow checks. For a real binary you want release mode:

cargo build --release
# output: Finished `release` profile [optimized] target(s) in 1.21s

./target/release/hello
# output: Hello, world!

Release builds are dramatically faster — often 10x to 100x — because the compiler turns on full optimisation. They also take longer to build, which is why you don’t use them during development.

The project on disk after one run

After your first cargo run, the directory looks like this:

ls
# output: Cargo.lock  Cargo.toml  src  target
  • Cargo.lock — pins the exact versions of every dependency. Commit it for binary projects, ignore it for library crates.
  • target/ — the build cache. Big. Git-ignore it. (Cargo generates a .gitignore for you automatically.)

You should never edit Cargo.lock by hand and you should never check target/ into version control.

Editor setup

Two editors dominate.

VS Code — install the rust-analyzer extension. It gives you autocompletion, inline errors, type hints on every line, and one-click formatting. This is what most beginners use.

RustRover — JetBrains’ paid Rust IDE. It is excellent and comes with a free non-commercial tier. If you already use IntelliJ or PyCharm, you will feel at home immediately.

Either way, you also want:

rustup component add rustfmt clippy
  • rustfmt auto-formats your code. Run cargo fmt to apply.
  • clippy is a linter that catches common mistakes and suggests idiomatic rewrites. Run cargo clippy to see warnings.

Both are official Rust tools and are worth running before every commit.

Try this. Inside src/main.rs, change the program to print your name and the result of a small calculation:

fn main() {
    let name = "Ada";
    println!("Hello, {}! 7 * 6 = {}", name, 7 * 6);
}

Run cargo run. Then run cargo fmt and watch the formatter clean up any indentation. Then run cargo clippy and read whatever it suggests.

Common install issues

linker 'cc' not found on Linux. You skipped the build-essential step. Install it as shown above.

link.exe not found on Windows. You declined the Visual Studio Build Tools prompt during rustup-init. Run rustup-init.exe again and accept this time, or install the Build Tools from Microsoft’s site separately.

cargo: command not found after install. Your shell hasn’t picked up the new PATH yet. Either open a new terminal or run source $HOME/.cargo/env.

Compilation feels slow. It will, especially on the first build of a project with many dependencies. Subsequent builds are incremental. cargo check and the rust-analyzer extension run far faster than cargo build, so use them during the edit loop.

Recap

You now have:

  • A working Rust toolchain installed via rustup, with rustc and cargo on your PATH.
  • A first project created with cargo new, containing Cargo.toml and src/main.rs.
  • An understanding of cargo run, cargo build, and cargo check, and when to reach for each.
  • The release-mode build with --release for shippable binaries.
  • rustfmt and clippy available as official tooling.

Next steps

The next post covers the actual language: how to declare variables with let, when to use mut, what shadowing is, and the scalar types — integers, floats, booleans, and chars — that the rest of the series builds on.

→ Next: Variables and Basic Types in Rust

Questions or feedback? Email codeloomdevv@gmail.com.