Installing Rust on Windows: A Detailed Guide

Introduction / Why You Need This

Rust is a modern systems programming language that provides memory safety and high performance. Installing Rust on Windows opens up opportunities for developing system software, embedded systems, web servers, and even game engines. This guide will help you set up a Rust development environment on Windows 10 or 11 from scratch, including the rustup toolchain manager, rustc compiler, and cargo build system. After completing these steps, you'll be able to compile and run Rust programs locally.

Prerequisites / Preparation

Before you begin, ensure that:

• You have Windows 10 (version 1809 or newer) or Windows 11 installed.
• You have an internet connection to download the tools (approximately 100 MB).
• You have write permissions to the %USERPROFILE% folder (usually C:\Users\YourUsername).
• (Optional) For Windows development using WinAPI or building projects with C dependencies, it's recommended to install Build Tools for Visual Studio (can be selected in the rustup installer or installed separately).

Step 1: Download the rustup Installer

rustup is the official Rust toolchain manager. It manages versions of the compiler, cargo, and documentation.

1. Open your browser and go to the official rustup page for Windows.
2. Click the «Download rustup-init.exe» button.
3. Save the file to a convenient location (e.g., Downloads).

Step 2: Run the Installer

1. Open PowerShell or Command Prompt (CMD) as an administrator (not strictly required, but recommended for automatic PATH addition).
2. Navigate to the folder where you downloaded the file, for example:

   cd $env:USERPROFILE\Downloads
   

3. Run the installer:

   .\rustup-init.exe
   

4. In the installer's text interface:
   • Press Enter to continue.
   • Select option «1) Proceed with installation (default)».
   • Ensure that «Add cargo to PATH» is selected (add cargo to PATH). This is critical.
5. Wait for the installation to complete. Rustup will download the latest stable version of Rust (the rustc compiler, cargo, and documentation).

Step 3: Verify the Installation

After installation, close and reopen your terminal (PowerShell or CMD) for the PATH changes to take effect.

Run the following commands to verify:

rustc --version

The output should look something like: rustc 1.78.0 (9b00959e5 2024-04-30) (version may vary).

cargo --version

Output: cargo 1.78.0 (54d8815d0 2024-04-30).

If the commands are not found, check your PATH: it should include %USERPROFILE%\.cargo\bin.

Step 4: Create and Run Your First Project

1. Create a new Rust project using cargo:

   cargo new hello-rust
   

   
   This creates a hello-rust folder with a basic project structure.
2. Navigate to the project folder:

   cd hello-rust
   

3. Build and run the project:

   cargo run
   

   
   You should see the output Hello, world!. This confirms that the compiler and build system are working correctly.

Verify the Result

A successful installation is confirmed by:

• The rustc --version and cargo --version commands output versions without errors.
• The hello-rust project builds and runs successfully, printing Hello, world!.
• The %USERPROFILE%\.cargo\ folder contains the rustc.exe, cargo.exe, and other binaries.

Potential Issues

Error: rustc or cargo are not recognized as commands

Cause: The path to %USERPROFILE%\.cargo\bin is not added to PATH or the terminal hasn't been restarted. Solution:

1. Restart your terminal (or computer).
2. Check PATH: in PowerShell, run $env:Path and ensure %USERPROFILE%\.cargo\bin is listed.
3. If not, add it manually:
   • Open "System Properties" → "Advanced" → "Environment Variables".
   • In "System variables" (or "User variables"), find Path, edit it, and add a new entry: %USERPROFILE%\.cargo\bin.
   • Restart your terminal.

Antivirus or Windows Defender blocks the installation

Cause: Some antivirus software may falsely flag installation scripts. Solution: Temporarily disable your antivirus during installation or add an exception for the %USERPROFILE%\.cargo\bin folder and the downloaded rustup-init.exe.

Build fails with errors related to link.exe or cl.exe

Cause: Compiling C dependencies requires Visual Studio Build Tools. Solution: Install Build Tools for Visual Studio (available via the rustup installer or separately from the official website). In the installer, select the "Desktop development with C++" workload.

Rustup cannot download components due to proxy

Cause: Corporate networks often use a proxy server. Solution: Configure a proxy for rustup using the HTTP_PROXY and HTTPS_PROXY environment variables. For example, in PowerShell:

$env:HTTP_PROXY="http://proxy.example.com:8080"
$env:HTTPS_PROXY="http://proxy.example.com:8080"

Then restart rustup: rustup self update or rustup toolchain install stable.