SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsrust-windows-setup

rust-windows-setup

Coding & development

View repository

Updated 10-16 07:23

About this skill

Robustly installing the Rust toolchain on Windows

What this skill solves

When setting up Rust on Windows, the real pitfalls are often not Rust itself, but three things:

  1. The official rustup source downloads slowly/is prone to dropping → the installation is interrupted by a timeout → the toolchain is only half installed → it reports error: Missing manifest in toolchain 'stable-x86_64-pc-windows-gnu'。
  2. A C compiler is needed(bundled features such as rusqlite and openssl-sys compile C code), and on Windows you either use MinGW's gcc or MSVC's cl.exe, both of which have PATH / environment variable pitfalls.
  3. The mirror and PATH were not set "globally"(only written in ~/.bashrc), causing them to stop working when you switch to PowerShell / cmd / VS Code terminal.

This skill gives a one-shot, done-right approach to avoid repeated reinstalls.

When to use

  • A new machine (especially a domestic Windows one) needs Rust installed from scratch.
  • Compilation reports Missing manifest。
  • When compiling a crate with C dependencies, it reports dlltool.exe: program not found or the linker cannot be found.
  • You want to make the Rust environment "ready to use out of the box in any terminal".

General principles

  • Set both the mirror and the environment variables at the Windows user level (registry), do not only write ~/.bashrc—— ~/.bashrc only takes effect in git-bash,rustup.exe is a Windows program, PowerShell/cmd cannot read it.
  • Prefer MSVC(Rust's default target on Windows), the least hassle; MinGW is the alternative.

Step 1: Set the rustup domestic mirror (prevents download timeouts, key)

Use PowerShell to write it into the Windows user environment variables (write with .NET, to avoid setx 's 1024-character truncation, and also avoid git-bash treating $ as variable expansion):

[Environment]::SetEnvironmentVariable("RUSTUP_DIST_SERVER", "https://rsproxy.cn", "User")
[Environment]::SetEnvironmentVariable("RUSTUP_UPDATE_ROOT", "https://rsproxy.cn/rustup", "User")

Verify (after opening any new terminal):

(Get-ItemProperty 'HKCU:\Environment').RUSTUP_DIST_SERVER

Should return https://rsproxy.cn。

Step 2: Set the cargo crates mirror (speeds up dependency downloads)

Create / append ~/.cargo/config.toml(cargo reads this file directly, independent of the shell):

[source.crates-io]
replace-with = "rsproxy-sparse"
[source.rsproxy-sparse]
registry = "sparse+https://rsproxy.cn/index/"
[registries.rsproxy]
index = "https://rsproxy.cn/crates.io-index"

Step 3: Install Rust

# 用国内镜像后的 rustup-init（下载快）
# 推荐直接装 MSVC 默认 target，见步骤四
winget install -e --id Rust.Rustup
# 或手动：
#  curl -sSf https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe -o rustup-init.exe
#  ./rustup-init.exe -y

Step 4: Choose a C toolchain (pick one, A recommended)

Option A (recommended): MSVC — the least hassle

A single Visual Studio Build Tools installer gives you both the C compiler cl.exe and the linker link.exe, and rustc will automatically locate it via vswhere link.exe，no need to configure PATH manually。

# 1. 装 VC++ Build Tools（含 MSVC v143 + Windows SDK，需管理员/UAC 弹窗）
winget install -e --id Microsoft.VisualStudio.2022.BuildTools `
  --override "--add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.Windows11SDK.26100 --includeRecommended --passive"

# 2. 装并切到 msvc target
rustup toolchain install stable-x86_64-pc-windows-msvc
rustup default stable-x86_64-pc-windows-msvc

# 3.（可选）卸掉 gnu，避免以后混淆
rustup toolchain uninstall stable-x86_64-pc-windows-gnu

Afterwards cargo build / cargo install no need to add --target, usable directly in any terminal.

Option B (alternative): MinGW gnu — PATH must be handled

# 1. 装 MSYS2
winget install -e --id MSYS2.MSYS2 --accept-package-agreements --accept-source-agreements --silent
# 2. 在 MSYS2 里装 mingw gcc + binutils（注意：第一次 pacman -Syu 会弹“关闭终端”确认，
#    非交互会杀掉进程；用 -Sy 只刷新再 -S 装，避开它）
#    C:\msys64\usr\bin\bash.exe -lc "pacman -Sy --noconfirm; pacman -S --needed --noconfirm mingw-w64-x86_64-gcc mingw-w64-x86_64-binutils"
# 3. 关键：把 C:\msys64\mingw64\bin 加进 Windows 用户 PATH（否则 dlltool/ld 找不到）

Add C:\msys64\mingw64\bin to the Windows user PATH (PowerShell, to avoid truncation):

$p = [Environment]::GetEnvironmentVariable("Path", "User")
if (-not $p.Contains("msys64\mingw64\bin")) {
  [Environment]::SetEnvironmentVariable("Path", ($p.TrimEnd(";") + ";C:\msys64\mingw64\bin"), "User")
  Write-Host "已添加 C:\msys64\mingw64\bin 到用户 PATH"
}

One-click script (optional)

This skill comes with scripts/setup-rust-windows.ps1, which completes it in one click under an administrator PowerShell: set the mirror, install rustup, install VC++ Build Tools, switch to the msvc target, verify.

powershell -ExecutionPolicy Bypass -File scripts/setup-rust-windows.ps1

Installing VS Build Tools will pop up UAC asking for administrator privileges; the remaining steps only need a normal user.

Step 5: Verify

Open any new terminal (to let the environment variables take effect):

rustc --version
cargo --version
cargo build        # 或 cargo build --target x86_64-pc-windows-gnu（方案 B）

Troubleshooting quick reference table

Error / symptom Root cause Solution
Missing manifest in toolchain 'stable-x86_64-pc-windows-gnu' The toolchain download timed out/was interrupted, so only half of it was installed First set up the rustup mirror (Step 1), then rustup toolchain uninstall <名字> → rustup toolchain install <名字> --profile minimal clean reinstall
In ~ type cargo to get help; enter the project directory and type cargo and it reports Missing manifest Illusion：cargo(no arguments) only prints help and does not invoke rustc, so it does not expose the broken toolchain; only when you enter the project does it actually parse the toolchain and blow up Just look at rustc --version; if it is broken, it is broken, so reinstall per the previous item
error: error calling dlltool 'dlltool.exe': program not found MinGW's dlltool is not in PATH (cc must be explicitly invoked during the linking stage) For Plan B, confirm that C:\msys64\mingw64\bin is already in the Windows user PATH (Step 4, Plan B.3)
cargo build is stuck at downloading N components for a long time The official rustup source is slow This must mean the mirror is not in effect; recheck Step 1 (whether there is an rsproxy value in HKCU\Environment)
Running in git-bash reg query / powershell reports a syntax error git-bash escaped/expanded the backslash and$ escaped/expanded powershell -Command Wrap the arguments ofsingle quotes; the \m in the regex is invalid, switch to .Contains() for literal substring matching

Notes

  • Mirror environment variables (Steps 1 and 2)only need to be set once, and after being written to the registry all new terminals inherit them automatically.
  • If the machine is overseas and the official source is not slow, you can skip the mirror steps, but PATH (no need to worry about it for Plan A / mandatory for Plan B) is still critical.
  • Motivating case: when adding pi support to mco-org/squad(Rust + rusqlite bundled), the entire chain was stepped through and verified according to this skill.