Building Rust from Source

Building Rust from source is not recommended unless you’re contributing to Rust or need a custom compiler build. If you just want to use Rust, see the standard installation methods instead.

Introduction

The Rust build system uses a Python script called x.py to build the compiler, which manages the bootstrapping process. This script lives at the root of the project and handles all aspects of building, testing, and installing Rust.

The Bootstrap Process

Since the Rust compiler is written in Rust, it must be built by a precompiled “snapshot” version of itself (made in an earlier stage of development). This means:

Source builds require an Internet connection to fetch snapshots
Your OS must be able to execute the available snapshot binaries
Only platforms with “host tools” support have pre-compiled snapshots available
To compile for platforms without host tools, you must cross-compile

See the Rust platform support documentation for a list of supported platforms and their tier levels.

Build Configuration

The build system uses a file named bootstrap.toml to determine various configuration settings. You can see a full list of options in bootstrap.example.toml.

Interactive Setup
Configure Script
Manual TOML

The easiest way to get started is with the interactive setup command:

./x.py setup

This will guide you through:

Selecting a config profile (compiler, library, tools, etc.)
Setting up LSP (rust-analyzer)
Configuring Git hooks
Other common development settings

For more control, use the configure script to generate bootstrap.toml:

./configure --enable-full-tools --enable-profiler

This is especially useful for creating complex configurations in a single command.

You can also create bootstrap.toml manually:

[build]
extended = true
tools = ["cargo", "clippy", "rustfmt"]

[llvm]
download-ci-llvm = true

[rust]
channel = "dev"

Running x.py

On most Unix systems, you can run x.py directly:

./x.py <subcommand> [flags]

Common subcommands include:

build - Build the compiler and standard library
test - Run the test suite
doc - Build documentation
install - Install the built compiler
check - Quick syntax check without full compilation
clippy - Run Clippy lints
fmt - Format code with rustfmt

./x.py build

Build Stages

The Rust build happens in stages:

Stage 0

Uses the downloaded snapshot compiler to build the build system and compile the stage 1 compiler.

Stage 1

Uses the stage 1 compiler to rebuild itself and produce the stage 2 compiler.

Stage 2

The stage 2 compiler is the final compiler and can build the standard library and tools.

By default, x.py build builds through stage 1. Use --stage 2 to build the final compiler.

Quick Reference

Command	Description
`./x.py setup`	Interactive configuration
`./configure`	Generate bootstrap.toml
`./x.py build`	Build compiler (stage 1)
`./x.py build --stage 2`	Build final compiler
`./x.py test`	Run test suite
`./x.py doc`	Build documentation
`./x.py install`	Install to system
`./x.py --help`	Show all options

Next Steps

Install Dependencies

Set up required dependencies for your platform

Unix Build Guide

Step-by-step instructions for Unix-like systems

Windows Build Guide

Step-by-step instructions for Windows

Configuration Options

Explore all configuration options

Additional Resources

Rustc Dev Guide - Comprehensive guide to compiler development
How to Build and Run - Detailed build instructions
Getting Started - Contributing to Rust

Getting Started

Building from Source

Architecture

Compiler

Standard Library

Tooling

Building Rust from Source

Introduction

The Bootstrap Process

Build Configuration

Running x.py

Build Stages

Quick Reference

Next Steps

Install Dependencies

Unix Build Guide

Windows Build Guide

Configuration Options

Additional Resources

Build docs developers (and LLMs) love

Getting Started

Building from Source

Architecture

Compiler

Standard Library

Tooling

​Introduction

​The Bootstrap Process

​Build Configuration

​Running x.py

​Build Stages

​Quick Reference

​Next Steps

Install Dependencies

Unix Build Guide

Windows Build Guide

Configuration Options

​Additional Resources

Build docs developers (and LLMs) love

Introduction

The Bootstrap Process

Build Configuration

Running x.py

Build Stages

Quick Reference

Next Steps

Additional Resources