msvc-kit

English | 中文
A portable MSVC Build Tools installer and manager for Rust/Windows.
TL;DR
# Install the CLI
cargo install msvc-kit
# Download latest MSVC + Windows SDK into default data dir
msvc-kit download
# Apply environment to current shell (PowerShell)
msvc-kit setup --script --shell powershell | Invoke-Expression
Features
- Download MSVC compiler from Microsoft servers
- Download Windows SDK to a chosen directory
- Auto environment setup for immediate use (cc-rs compatible)
- Version management for host/target architectures (x64, x86, arm64, arm)
- Library API for programmatic usage
- Resumable downloads with redb-based index for fast skip
- Manifest caching with ETag/Last-Modified conditional requests
- TLS backend uses
native-tls (Windows schannel) to avoid rustls/awslc-sys build issues
- Multi-format extraction (VSIX, MSI, CAB)
- Hash verification with SHA256
- Self-update via axoupdater, compatible with cargo-dist releases
Installation
- Via Winget (Recommended)
winget install loonghao.msvc-kit
- Via PowerShell Script
irm https://github.com/loonghao/msvc-kit/releases/latest/download/install.ps1 | iex
- From crates.io
cargo install msvc-kit
- Pre-built Binaries
# Download and extract to a directory in your PATH
Invoke-WebRequest -Uri "https://github.com/loonghao/msvc-kit/releases/latest/download/msvc-kit-x86_64-pc-windows-msvc.zip" -OutFile msvc-kit.zip
Expand-Archive msvc-kit.zip -DestinationPath $env:USERPROFILE\.cargo\bin -Force
- From source
git clone https://github.com/loonghao/msvc-kit.git
cd msvc-kit
cargo install --path .
Development (vx)
This project uses vx to manage toolchains and runs all commands through the justfile.
# Install tools defined in vx.toml
vx setup
# List available commands
vx just --list
# Run the full CI pipeline locally
vx just ci
Release bundles
- On every tagged release (or release-please cut), CI builds and uploads
msvc-bundle---.zip for x64, x86, and arm64 directly to the GitHub Release.
- Bundles are created via
msvc-kit bundle --accept-license; by downloading you agree to the Microsoft Visual Studio License Terms.
Quick Start (CLI)
Download
# Latest versions
msvc-kit download
# Specify versions / dirs / arch
# MSVC version can be short (14.44) or full (14.44.34823)
msvc-kit download \
--msvc-version 14.44 \
--sdk-version 10.0.26100.0 \
--target C:\msvc-kit \
--arch x64 \
--host-arch x64
# Download only MSVC (skip SDK)
msvc-kit download --no-sdk
# Download only SDK (skip MSVC)
msvc-kit download --no-msvc
# Control parallel downloads (default: 4)
msvc-kit download --parallel-downloads 8
# Skip hash verification
msvc-kit download --no-verify
> Note: MSVC version can be specified as short format (e.g., 14.44) which auto-resolves to the latest build, or full format (e.g., 14.44.34823) for a specific build.
Windows SDK extraction notes
Windows SDK payloads contain MSI installers plus adjacent CAB source media. Keep the download cache intact while extraction runs; deleting individual CAB files can make Windows Installer fail with 1619.
Some optional SDK MSI packages, such as Application Verifier and WinRT Intellisense, are not required for MSVC/Rust toolchains and may fail administrative extraction with 1603 on long or constrained paths. msvc-kit skips those optional MSI packages and keeps extracting the SDK headers, libraries, tools, and redistributables needed for compilation.
If SDK extraction still fails:
- Prefer a short target directory, for example
msvc-kit download --target C:\msvc-kit.
- Clear the SDK cache and retry if the error mentions missing source media:
msvc-kit clean --all --cache.
- Wait for Windows Update or another installer if the error is
1618.
- Set
RUST_LOG=debug when reporting an issue so the failing MSI, target directory, and extraction plan are visible.
Developer guidance:
- Treat SDK CAB files as MSI source media, not standalone archives to unpack.
- Keep non-essential SDK MSI packages opt-out/skippable unless they are needed by a verified compiler workflow.
- Use short or normalized paths for
msiexec whenever possible, and keep tests for known-problem package names so manifest changes do not reintroduce the regression.
Version Compatibility Quick Reference:
| Scenario | MSVC | SDK | Command |
|---|
| Latest (recommended) | 14.44 | 10.0.26100.0 | msvc-kit download |
| Windows 11 development | 14.42+ | 10.0.22621.0+ | msvc-kit download --sdk-version 10.0.22621.0 |
| Maximum Win10 compat | 14.40 | 10.0.19041.0 | msvc-kit download --msvc-version 14.40 --sdk-version 10.0.19041.0 |
See Version Compatibility Guide for detailed information.
Setup Environment
# Generate script for current shell
msvc-kit setup --script --shell powershell | Invoke-Expression
# Or for CMD
msvc-kit setup --script --shell cmd > setup.bat && setup.bat
# Portable script (rewrites install root to %~dp0runtime)
msvc-kit setup --script --shell cmd --portable-root "%~dp0runtime" > setup.bat
# Or for Bash/WSL
eval "$(msvc-kit setup --script --shell bash)"
# Persist to Windows registry (requires admin)
msvc-kit setup --persistent
Create Portable Bundle
Create a self-contained bundle with MSVC toolchain that can be used anywhere:
# Create bundle (requires accepting Microsoft license)
msvc-kit bundle --accept-license
# Specify output directory and architecture
msvc-kit bundle --accept-license --output ./my-msvc-bundle --arch x64
# Cross-compilation bundle (x64 host targeting ARM64)
msvc-kit bundle --accept-license --host-arch x64 --arch arm64
# Also create a zip archive
msvc-kit bundle --accept-license --zip
# Specify versions
msvc-kit bundle --accept-license --msvc-version 14.44 --sdk-version 10.0.26100.0
The bundle contains:
msvc-kit.exe - CLI tool
VC/Tools/MSVC/{version}/ - MSVC compiler and tools
Windows Kits/10/ - Windows SDK
setup.bat - CMD activation script
setup.ps1 - PowerShell activation script
setup.sh - Bash/WSL activation script
README.txt - Usage instructions
Usage:
# Extract and run setup script
cd msvc-bundle
setup.bat # CMD
.\setup.ps1 # PowerShell
source setup.sh # Bash/WSL
# Now cl, link, nmake are available
cl /nologo test.c
List Versions
msvc-kit list # Show installed versions
msvc-kit list --available # Show available versions from Microsoft
Clean Up
msvc-kit clean --msvc-version 14.44 # Remove specific MSVC version
msvc-kit clean --sdk-version 10.0.26100.0 # Remove specific SDK version
msvc-kit clean --all # Remove all installed versions
msvc-kit clean --all --cache # Also clear download cache
Configuration
Config file: %LOCALAPPDATA%\loonghao\msvc-kit\config\config.toml
msvc-kit config # Show current config
msvc-kit config --set-dir C:\msvc-kit # Set install directory
msvc-kit config --set-msvc 14.44 # Set default MSVC version
msvc-kit config --set-sdk 10.0.26100.0 # Set default SDK version
msvc-kit config --reset # Reset to defaults
Print Environment Variables
msvc-kit env # Print as shell script
msvc-kit env --format json # Print as JSON
Self-Update
# Check for updates without installing
msvc-kit update --check
# Update to the latest version
msvc-kit update
# Update to a specific version
msvc-kit update --version 0.2.5
The self-update feature is powered by axoupdater and queries GitHub Releases directly. It is compatible with both cargo-dist and custom release workflows. During installation, msvc-kit pins the update to the current install root and verifies that the updated executable reports the expected version before declaring success. The self-update feature is enabled by default and can be disabled with --no-default-features at build time.
Install MSVC into Visual Studio (UBT Discovery)
Unreal Build Tool (UBT) discovers MSVC toolchains by scanning Visual Studio's
installation directory. When msvc-kit downloads a toolchain to a custom
location (e.g. C:\msvc-kit\14.36), UBT cannot find it. The
install-into-vs subcommand copies the toolchain files into VS's toolchain
directory, making them visible to UBT.
# Check VS instances and their registered MSVC versions
msvc-kit install-into-vs --check
# Install a specific downloaded toolchain into VS
msvc-kit install-into-vs --dir C:\msvc-kit\14.36
# Auto-detect and install the latest downloaded toolchain
msvc-kit install-into-vs --auto
> ⚠️ This command usually requires administrator privileges because it writes
> to C:\Program Files (x86)\Microsoft Visual Studio\....
UE 5.2 + MSVC 14.36 CI Integration Example:
When building Unreal Engine plugins via GitHub Actions self-hosted runners,
msvc-kit can provision the exact MSVC version required by the engine:
- name: Ensure MSVC 14.36 toolchain
shell: pwsh
run: |
$msvcKitExe = "C:\msvc-kit\bin\msvc-kit.exe"
$msvcTargetDir = "C:\msvc-kit\14.36"
# Download if not cached
if (-not (Test-Path "$msvcTargetDir\VC\Tools\MSVC")) {
& $msvcKitExe download --msvc-version 14.36 --no-sdk --dir $msvcTargetDir --arch x64
}
# Activate toolchain for this job
$envScript = & $msvcKitExe setup --script --shell powershell --dir $msvcTargetDir
if ($LASTEXITCODE -ne 0) { throw "msvc-kit setup failed" }
Invoke-Expression ($envScript -join "`n")
# Install into VS for UBT discovery (requires admin)
& $msvcKitExe install-into-vs --dir $msvcTargetDir
Caching & Progress
Caching & Progress
| Cache Type | Location | Description |
|---|
| Download index | downloads/{msvc|sdk}/.../index.db | redb database for tracking download status |
| Manifest cache | cache/manifests/ | Cached VS manifests with ETag/Last-Modified |
| Extraction markers | .msvc-kit-extracted/ | Skip already-extracted packages |
- Progress display: Single-line spinner by default. Set
MSVC_KIT_INNER_PROGRESS=1 for detailed file progress.
- Skip logic: Downloads are skipped when:
cached: File exists in index with matching hash
304: Server returns Not Modified (ETag/Last-Modified match)
size match: File size matches expected (best-effort, noted in code)
TLS Backend Configuration
By default, msvc-kit uses native-tls (SChannel on Windows) to avoid requiring cmake and NASM during compilation. This resolves the aws-lc-sys build issue.
| Feature | TLS Backend | Build Requirements | Default |
|---|
native-tls | Platform native (SChannel/OpenSSL) | None | ✓ |
rustls-tls | rustls + aws-lc-rs | cmake, NASM | - |
# Default: native-tls (recommended, no extra build deps)
[dependencies]
msvc-kit = "0.2"
# Or explicitly choose a TLS backend:
msvc-kit = { version = "0.2", default-features = false, features = ["native-tls"] }
# Use rustls instead (requires cmake + NASM on Windows):
msvc-kit = { version = "0.2", default-features = false, features = ["rustls-tls"] }
Library Usage
[dependencies]
msvc-kit = "0.2"
use msvc_kit::{
download_msvc, download_sdk, extract_and_finalize_msvc, extract_and_finalize_sdk,
setup_environment, DownloadOptions,
};
use msvc_kit::{list_available_versions, Architecture};
#[tokio::main]
async fn main() -> msvc_kit::Result<()> {
// List available versions from Microsoft
let versions = list_available_versions().await?;
println!("Latest MSVC: {:?}", versions.latest_msvc);
println!("Latest SDK: {:?}", versions.latest_sdk);
// Download with builder pattern
let options = DownloadOptions::builder()
.target_dir("C:/msvc-kit")
.arch(Architecture::X64)
.build();
let mut msvc = download_msvc(&options).await?;
let sdk = download_sdk(&options).await?;
extract_and_finalize_msvc(&mut msvc).await?;
extract_and_finalize_sdk(&sdk).await?;
let env = setup_environment(&msvc, Some(&sdk))?;
println!("cl.exe: {:?}", env.cl_exe_path());
Ok(())
}
See Library API Documentation for full API reference.
Architecture Support
| Architecture | Host | Target | Description |
|---|
x64 | ✓ | ✓ | 64-bit x86 |
x86 | ✓ | ✓ | 32-bit x86 |
arm64 | ✓ | ✓ | ARM64 |
arm | - | ✓ | ARM 32-bit (target only) |
License
MIT License - see LICENSE.
Important: Microsoft Software License Notice
The MSVC compiler and Windows SDK downloaded by this tool are property of Microsoft
and subject to Microsoft Visual Studio License Terms.
- msvc-kit itself is MIT licensed
- MSVC Build Tools and Windows SDK are NOT redistributable - users must download them directly
- By using
msvc-kit download or msvc-kit bundle --accept-license, you agree to Microsoft's license terms
- This tool automates the download process; it does not redistribute Microsoft software