Install Rust With Rustup and Set Up Your First Project
Install the Rust toolchain with rustup, check that it works, pick a channel and create your first Cargo project, with the three problems that stop most first installs.

Rust installs from one tool and one command. There is no package manager to wrestle with, no version of the compiler pinned to your operating system and no root access required, because everything goes into your home directory. This post covers the install, what it puts on your machine, the first project, the one failure that stops people on a new computer, and how to pin a toolchain so a team stays in step. The outputs shown were captured on a machine running Rust 1.99.0, so version numbers in your terminal will be newer.
Install
The official installer is a shell script that downloads rustup, which then downloads the compiler:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shThe script asks whether to proceed with the default installation, and choosing the default installs the stable toolchain for your platform, with cargo, clippy and rustfmt included. On Windows, download rustup-init.exe from rust-lang.org and run it; it needs the Visual Studio C++ build tools, which the installer points you to. I did not re-run the installer on this machine, which already has Rust, so there is no installer transcript below. The checks after it are real.
Open a new terminal, because the installer adds ~/.cargo/bin to your PATH through your shell profile and the current shell has not read it yet. Then:
rustup --version
rustc --version
cargo --versionrustup 1.29.1 (d95a37b6a 2026-08-13)
rustc 1.99.0 (b940084d7 2026-09-28)
cargo 1.99.0 (5f94df478 2026-08-27)rustup is the toolchain manager, rustc is the compiler and cargo is the build tool and package manager. All three live in ~/.cargo/bin as small launchers. rustup is the thing that decides which actual compiler rustc runs, which is how one machine can hold several versions.
What got installed
rustup show lists the toolchains, the active one and the compilation targets:
rustup showDefault host: aarch64-apple-darwin
rustup home: ~/.rustup
installed toolchains
--------------------
stable-aarch64-apple-darwin (active, default)
nightly-aarch64-apple-darwin
active toolchain
----------------
name: stable-aarch64-apple-darwin
active because: it's the default toolchain
installed targets:
aarch64-apple-darwinA toolchain is a compiler plus its standard library and tools, tied to a release channel. stable ships every six weeks; beta and nightly are the channels ahead of it. A target is a platform you can compile for: the host target is whatever you installed on, and rustup target add brings in others for cross-compiling, which is covered in cross compilation. Components are optional parts of a toolchain such as clippy (a linter) and rustfmt (a formatter). For the longer explanation of how these fit together, read Rustup explained.
The toolchains live in ~/.rustup/toolchains, and one stable toolchain with its documentation took 1.0 GB on this machine, so budget a few gigabytes if you plan to keep several. Nothing is installed system wide, and rustup self uninstall removes everything.
The first project
Make a project and run it:
cargo new hello
cd hello
cargo runcargo new writes three things. The manifest:
[package]
name = "hello"
version = "0.1.0"
edition = "2024"
[dependencies]and src/main.rs:
fn main() {
println!("Hello, world!");
}and a .gitignore for target if you are not already in a repository. The edition field picks the version of the language rules; new projects get the newest, 2024 here, and old crates keep working with their own edition. Cargo.toml explained describes the rest of the file.
cargo run compiles the project and runs the result:
Compiling hello v0.1.0 (~/hello)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.51s
Running `target/debug/hello`
Hello, world!The first line says Cargo compiled the hello package. The profile, dev, is unoptimised and carries debug information, which is what you want while developing; it finished in half a second for a program this small. The third line shows the path of the binary Cargo launched, in target/debug. The compiled program is an ordinary executable that you can copy anywhere, and it needs no Rust installation to run.
Build the optimised version with cargo build --release. The two binaries from this project:
debug target/debug/hello 474424 bytes
release target/release/hello 435024 bytesThey are close in size because a hello world is mostly the standard library's runtime and the formatting machinery, and 435 KB is unremarkable. Optimisation matters for real programs, where a release build can be an order of magnitude faster, as discussed in release and debug speed.
Run the two commands that every project should pass before you commit:
cargo fmt --check
cargo clippycargo fmt rewrites code to the standard style and --check only reports. cargo clippy prints suggestions beyond what the compiler warns about. Both printed nothing wrong for the hello project.
The failure on a new computer: no linker
Rust compiles your code itself but uses the system's C toolchain to link the final executable. A machine that has no compiler tools installed builds the crates fine and then fails at the last step. You can see the shape of that failure by pointing Cargo at a linker that does not exist:
RUSTFLAGS="-C linker=nonexistent-cc" cargo builderror: linker `nonexistent-cc` not found
|
= note: No such file or directory (os error 2)
error: could not compile `hello` (bin "hello") due to 1 previous errorOn a real fresh machine the name in that message is cc. The fix depends on the operating system. On macOS run xcode-select --install. On Debian and Ubuntu install build-essential. On Fedora install gcc. On Windows install the Visual Studio C++ build tools. The error usually appears after a long compile, which is why running cargo run on the hello project right after installing is worth doing: it fails in half a second instead of in the middle of your first real build. The longer story, including the messages specific to each platform, is in linking with cc failed.
Pin the toolchain for a project
Without any configuration, cargo uses your default toolchain. A project can override it with a file at its root:
[toolchain]
channel = "nightly"
components = ["rustfmt", "clippy"]Saved as rust-toolchain.toml, that makes every command inside the directory use the nightly channel, whatever your default is:
$ rustc --version
rustc 1.101.0-nightly (249c1e4e3 2026-11-05)
$ cargo --version
cargo 1.101.0-nightly (3c747ea3e 2026-11-03)Without the file the same commands report the stable toolchain from the start of this post. For a real project you pin a release number such as channel = "1.99" instead of nightly, so that everyone building it, on any machine and in CI, uses one compiler. rustup downloads the toolchain automatically the first time someone enters the directory. The first time I used it here the pinned nightly toolchain was refreshed and two components downloaded before the command ran, which is the one-time cost. The file format and the override rules are in rust-toolchain.toml.
Keeping Rust up to date
Nothing updates behind your back:
rustup checkstable-aarch64-apple-darwin - update available: 1.99.0 (b940084d7 2026-09-28) -> 1.99.1 (58cf8f9c3 2026-10-13)
nightly-aarch64-apple-darwin - up to date: 1.101.0-nightly (249c1e4e3 2026-11-05)
rustup - update available : 1.29.1 -> 1.29.3On this machine a newer stable (1.99.1) and a newer rustup were available. rustup update installs them, and Rust's stability promise means that code which compiled on an earlier stable compiles on the next one, so updating is low risk. Update when you want a new language feature or a fix, not on a schedule.
Set up your editor
The one tool worth installing next is rust-analyzer, the language server that gives you completion, inline errors and type hints. In VS Code, install the "rust-analyzer" extension; in other editors it is a plugin or a built-in language server setting. It reads your Cargo.toml and uses the same toolchain as the command line. Setup details are in rust-analyzer setup.
Where this does not apply
If your operating system packages Rust (Debian, Fedora and Homebrew all do), you can install that instead, and it works; the trade-off is that the package is usually a few versions behind and cannot hold several toolchains or targets side by side. In a container, use the official rust Docker image rather than installing rustup in a Dockerfile layer. In a locked-down corporate environment where scripts piped into a shell are forbidden, rust-lang.org lists standalone installers that you can download, verify and run. And if you only want to try a snippet, the Rust Playground in the browser needs no installation at all.
Next steps
Read the language tour for the whole language in one sitting, and then hello world explained for what each line of the program you just ran does.


