Getting started

This page summarizes how to build, test, and run rustc from source. It mirrors the relevant parts of INSTALL.md, src/bootstrap/README.md, and the upstream rustc-dev-guide. Read those for the authoritative, kept-current versions.

If you only want to use Rust, this page is the wrong page — install via rustup.rs instead. This page is for building Rust from source.

Prerequisites

Dependency	Notes
Python	3 or 2.7 — required to bootstrap (bootstrap.py)
git	Recent — submodules and subtrees are heavily used
C/C++ toolchain	cc for host builds; g++/clang++/MSVC for LLVM source builds
curl	Used to download stage 0 artifacts (Windows uses PowerShell instead)
cmake, ninja	Only if building LLVM from source (skip with llvm.download-ci-llvm = true)
pkg-config, libiconv	Linux host builds
OpenSSL	Required to build Cargo

On most tier 1 / tier 2 platforms you should set llvm.download-ci-llvm = true in bootstrap.toml to avoid an LLVM source build (which can take more than an hour).

Initial setup

git clone https://github.com/rust-lang/rust
cd rust
./x setup     # interactive — picks a profile and sets up bootstrap.toml + git hooks

x setup writes a bootstrap.toml and offers profiles such as:

• library — work on library/ (std, core, alloc); fast incremental builds
• compiler — work on the rustc compiler (compiler/)
• tools — work on tools under src/tools/
• codegen — building LLVM from source for codegen work
• dist — full distribution build (slow)
• none — no opinion; you fill in bootstrap.toml yourself

You can edit bootstrap.toml directly — the documented set of options lives in bootstrap.example.toml.

The x entry point

All build/test/install actions go through x (a Python script under the hood):

./x build           # build a usable stage 1 toolchain
./x build library   # build only std/core/alloc
./x build compiler  # build only the compiler
./x check           # cargo check (very fast)
./x test            # run the full test suite (slow!)
./x test tests/ui   # run a single suite
./x doc             # build all the books and rustdoc output
./x fmt             # run rustfmt over the tree
./x clippy          # run clippy
./x clean           # wipe the build dir
./x install         # install built toolchain to a prefix

Common flags:

• --stage N — build through stage N. Default is 1 for most subcommands; use 2 for distribution-quality output.
• --keep-stage N — skip rebuilding earlier stages when iterating on a later one
• -i / --incremental — enable rustc's own incremental cache when building
• --bless — re-record snapshot/.stderr/.stdout outputs in tests
• -v, -vv — verbose / very verbose

See ./x --help and ./x build --help for the full list, plus the [build], [rust], [llvm], and [install] sections of bootstrap.example.toml.

Iterating quickly

The fastest dev loop for compiler work is roughly:

./x check                          # ~seconds: type-check the compiler
./x build library                  # rebuild std on top of stage 0
./x build --stage 1 compiler       # build a stage 1 rustc
./x test tests/ui/...some-test...  # run a focused test
./x test tests/ui/... --bless      # re-bless any stale .stderr files

For typical UI test work, --stage 1 plus a narrow test path is the sweet spot. For codegen / std work, --stage 1 library is usually enough. Avoid --stage 2 unless you specifically need it.

A few files reward keeping in your editor:

• bootstrap.toml — your local config
• triagebot.toml — labels, ping groups, mention rules
• rust-bors.toml — merge queue config
• Cargo.toml — the workspace root

Tooling

• rustfmt — formatting, configured by rustfmt.toml. Run ./x fmt.
• tidy (src/tools/tidy/) — repository-wide lint (license headers, alphabetical lists, file size, banned patterns). Runs as part of ./x test tidy.
• clippy (src/tools/clippy/) — run via ./x clippy.
• typos — configured by typos.toml.

If you have a bootstrap.toml-edited config, also see change_tracker.rs (src/bootstrap/src/utils/change_tracker.rs) — bootstrap detects breaking config changes and prompts you on first run.

Common gotchas

• Forgot to set download-ci-llvm? — Source LLVM builds take a long time. Set [llvm] download-ci-llvm = true in bootstrap.toml.
• Out-of-date stage 0? — If you just synced main, run ./x clean after major bootstrap changes; the stage0 file pins versions.
• Tests fail with "stderr does not match" — Re-bless with ./x test ... --bless if your change is intentional, or fix the diagnostic.
• ./x test takes forever — Run a subset (./x test tests/ui/path/to/test.rs). The full suite is multi-hour even on fast hardware.

Where to ask for help

• Rust Zulip — #new-members for first-timers, then domain-specific streams (#t-compiler, #t-libs, #t-types, etc.)
• rustc-dev-guide — the deep manual
• rust-internals — design discussion forum