Installing Rust on macOS

Installing Rust on macOS sets up two primary components: the C linker and platform SDK provided by Apple's Xcode Command Line Tools, and the Rust toolchain (rustc, cargo, rustup, and standard library components) managed by rustup.

Architecture and Platform Targets

macOS runs on two processor architectures, and rustup automatically selects the native target triple matching your hardware:

Mac Hardware	Target Triple	Architecture	Minimum Supported macOS (Tier 1)
Apple Silicon (M1, M2, M3, M4)	`aarch64-apple-darwin`	64-bit ARM (`arm64`)	macOS 11.0 (Big Sur) or newer
Intel Mac	`x86_64-apple-darwin`	64-bit x86 (`x86_64`)	macOS 10.12 (Sierra) or newer

Both targets have Tier 1 support, meaning every commit to the Rust repository is built and passes the full automated test suite on both architectures before merging.

Step 1: Install Xcode Command Line Tools

rustc compiles Rust source code into machine object files, but it relies on the platform's system linker (cc / ld) and macOS SDK headers to produce a final executable binary. On macOS, these tools are distributed in the Xcode Command Line Tools package.

Install them from the Terminal before installing Rust:

xcode-select --install

Running this command opens a macOS dialog asking to download and install the command line developer tools. Once the installation finishes, verify that the path and clang linker are active:

xcode-select -p
cc --version

/Library/Developer/CommandLineTools
Apple clang version 16.0.0 (clang-1600.0.26.6)
Target: arm64-apple-darwin24.3.0
Thread model: posix
InstalledDir: /Library/Developer/CommandLineTools/usr/bin

If full Xcode is installed from the Mac App Store, xcode-select -p outputs /Applications/Xcode.app/Contents/Developer instead. Either path provides the linker required by rustc.

Step 2: Run the `rustup` Installer

The official way to install Rust on macOS is via rustup, the Rust toolchain installer and version manager. Run the following command in Terminal:

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

`curl` Flag	Purpose
`--proto '=https'`	Restricts connections strictly to HTTPS and refuses plain HTTP redirects
`--tlsv1.2`	Requires TLS version 1.2 or newer for transport encryption
`-sS`	Runs silently (hiding the progress meter) while still printing errors (`-S`) if the download fails
`-f`	Fails immediately on HTTP server errors (such as `404` or `500`) instead of piping an HTML error page into `sh`

Interactive Installer Options

The installer detects your macOS architecture, displays the directories it will modify, and presents three installation choices:

Current installation options:

   default host triple: aarch64-apple-darwin
     default toolchain: stable (default)
               profile: default
  modify PATH variable: yes

1) Proceed with standard installation (default - just press enter)
2) Customize installation
3) Cancel installation
>

Pressing Enter (or typing 1) installs the latest stable toolchain with the default profile (rustc, cargo, rustfmt, clippy, and rust-docs) and adds ~/.cargo/bin to your shell configuration files.

Non-Interactive Installation

For automated scripts, dotfiles, or CI environments, pass flags directly to the installer script using sh -s --:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable --profile default

Installer Flag	Description
`-y`	Disables the confirmation prompt and installs with the selected options
`--default-toolchain <name>`	Sets the initial toolchain (`stable`, `beta`, `nightly`, or a specific version like `1.85.0`)
`--profile <profile>`	Chooses which components to install: `minimal` (`rustc`, `cargo`, `rust-std`), `default` (adds `rustfmt`, `clippy`, `rust-docs`), or `complete`
`--no-modify-path`	Prevents the installer from editing `~/.zshenv`, `~/.zprofile`, or `~/.bash_profile`

Step 3: Configure the Shell Environment

rustup installs all executable shims (rustc, cargo, rustup, rustfmt, cargo-clippy, rustdoc) into ~/.cargo/bin.

To make these commands available in your currently open Terminal session without restarting the terminal, source the environment script generated by the installer:

. "$HOME/.cargo/env"

How macOS `zsh` Loads `~/.cargo/bin`

macOS uses zsh as its default login shell. During standard installation, rustup appends the following line to your profile configuration (such as ~/.zshenv and ~/.bash_profile):

. "$HOME/.cargo/env"

Inside ~/.cargo/env, the script safely prepends ~/.cargo/bin to PATH only if it is not already present:

#!/bin/sh
# rustup shell setup
# affix colons on either side of $PATH to simplify matching
case ":${PATH}:" in
    *:"$HOME/.cargo/bin":*)
        ;;
    *)
        # Prepending path in case a system-installed rustc needs to be overridden
        export PATH="$HOME/.cargo/bin:$PATH"
        ;;
esac

Directory Layout on macOS

Unlike system packages that scatter files across /usr/local/, rustup keeps the entire Rust installation inside two hidden directories in your home folder (~):

$HOME (/Users/username)
├── .cargo/
│   ├── bin/                  <-- Proxy binaries on PATH (rustc, cargo, rustup, rustfmt)
│   ├── env                   <-- Shell script that adds ~/.cargo/bin to PATH
│   └── registry/             <-- Cached crates downloaded by Cargo
└── .rustup/
    ├── settings.toml         <-- Active default toolchain and configuration
    └── toolchains/
        └── stable-aarch64-apple-darwin/
            ├── bin/          <-- Actual compiler and tool binaries
            ├── lib/          <-- Precompiled standard library (rlib) for target platforms
            └── share/doc/    <-- Offline HTML documentation (opened via rustup doc)

When you run rustc or cargo, you are invoking a lightweight proxy binary in ~/.cargo/bin that checks ~/.rustup/settings.toml (or any directory-specific override) and forwards execution to the active toolchain in ~/.rustup/toolchains/.

Step 4: Verify the Installation

Confirm that the tools are accessible on your PATH and pointing to ~/.cargo/bin:

which rustc cargo rustup
rustc --version
cargo --version
rustup --version

/Users/username/.cargo/bin/rustc
/Users/username/.cargo/bin/cargo
/Users/username/.cargo/bin/rustup
rustc 1.85.0 (4d91de4e4 2025-02-17)
cargo 1.85.0 (d73d2caf9 2024-12-31)
rustup 1.28.1 (f9edccde0 2025-03-05)

To verify that rustc can invoke the macOS linker and produce a native Mach-O executable, compile a one-line program from standard input:

echo 'fn main() { println!("Rust on macOS works!"); }' | rustc - -o test_mac && ./test_mac && rm test_mac

Rust on macOS works!

Homebrew vs Official `rustup` Installer

macOS users who manage packages with Homebrew (brew) have two related formulas available, which behave differently from the official installer:

Installation Method	Command	Pros and Cons
Official `rustup` script	`curl ... https://sh.rustup.rs \| sh`	Recommended. Full support for switching toolchains (`stable`, `nightly`), cross-compiling (`rustup target add`), and `rust-analyzer` integration
Homebrew `rustup`	`brew install rustup`	Installs `rustup-init` via Homebrew; still requires running `rustup-init` manually and configuring `PATH`
Homebrew `rust`	`brew install rust`	Installs a single standalone `rustc` and `cargo` in `/opt/homebrew/bin`. Cannot use `rustup toolchain` or `rustup target add`

If brew install rust was previously installed on your Mac, having both /opt/homebrew/bin/rustc and ~/.cargo/bin/rustc on your PATH can cause version mismatches in IDEs. Remove the standalone Homebrew formula with brew uninstall rust before using rustup.

Updating and Uninstalling

To update all installed toolchains and rustup itself to the newest release:

rustup update

To completely remove Rust, Cargo, all installed toolchains, and the PATH entries from your macOS user account:

rustup self uninstall

Common macOS Installation Errors

Missing or Broken Command Line Tools (`xcrun` Error)

After a major macOS system upgrade, the Command Line Tools path can become invalidated, causing compilation to fail at the linking step:

error: linking with `cc` failed: exit status: 1
  |
  = note: xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools),
          missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

Reset and reinstall the Command Line Tools to restore xcrun and the system linker:

sudo xcode-select --reset
xcode-select --install

`command not found: rustc` After Installation

If zsh: command not found: rustc appears immediately after installation, the current shell has not reloaded its environment configuration. Either open a new Terminal tab or run:

source "$HOME/.cargo/env"