Building Windows

Use PowerShell 7 (pwsh.exe) instead of the default powershell.exe. If you run into problems, open an issue on aphrody-labs/bun.

Prerequisites

Enable Scripts

By default, running unverified scripts is blocked.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted

System Dependencies

Bun v1.1 or later. The build uses Bun to run its own code generators.

irm https://bun.aphrody.com/install.ps1 | iex

Visual Studio with the "Desktop Development with C++" workload. While installing, also install Git if Git for Windows is not already installed.

Install Visual Studio with the graphical wizard or through WinGet:

winget install "Visual Studio Community 2022" --override "--add Microsoft.VisualStudio.Workload.NativeDesktop Microsoft.VisualStudio.Component.Git " -s msstore

After Visual Studio, you need the following:

• LLVM 23.1.1
• Go
• Rust (via rustup)
• NASM
• Ruby
• Node.js

Use Scoop to install these remaining tools.

irm https://get.scoop.sh | iex
scoop install nodejs-lts go rustup nasm ruby ccache
# scoop seems to be buggy if you install llvm and the rest at the same time
scoop install llvm@23.1.1

For Windows ARM64, download LLVM 23.1.1 directly from GitHub releases:

# Download and install LLVM for ARM64
Invoke-WebRequest -Uri "https://github.com/llvm/llvm-project/releases/download/llvmorg-23.1.1/LLVM-23.1.1-woa64.msi" -OutFile "$env:TEMP\LLVM-23.1.1-woa64.msi"
Start-Process msiexec.exe -ArgumentList "/i `"$env:TEMP\LLVM-23.1.1-woa64.msi`" /qn" -Wait

To build WebKit locally (optional, x64 only), install these packages:

scoop install make cygwin python

bun run build loads the Visual Studio environment itself. It resolves the toolchain natively with bun msvc sync, without vswhere.exe or vcvarsall.bat, and caches it in %LOCALAPPDATA%\bun\msvc. When the installed bun has no msvc command, it runs the same code through cargo run --bin bun-msvc from vendor/find-msvc-tools. To check the toolchain, or to install what is missing:

bun msvc doctor
bun msvc setup --toolset 14.44

To run MSVC tools by hand, load the environment into the current PowerShell terminal. Either script works:

. "$(bun msvc sync --toolset 14.44)\env.ps1"
.\scripts\vs-shell.ps1

Building

bun run build

A successful build writes bun-debug.exe to the build/debug folder.

.\build\debug\bun-debug.exe --revision

Add this folder to $Env:PATH: open the Start menu, type "Path", and use the environment variables menu to add C:\.....\bun\build\debug to the user environment variable PATH. Then restart your editor (if it still does not pick up the change, log out and log back in).

Extra paths

• The build extracts WebKit to $Env:BUN_INSTALL\build-cache\webkit-<version>-debug (webkit-<version>-arm64-debug on ARM64); BUN_INSTALL defaults to ~\.bun. Set $Env:BUN_BUILD_CACHE_DIR to put the build cache somewhere else.

Tests

Run the test suite with bun-debug test <path> or with the wrapper script bun run test <path>. The bun run test command runs every test file in a separate instance of bun-debug.exe, so a crash in the test runner does not stop the entire suite.

# Run the entire test suite with reporter
# the package.json script "test" uses "build/debug/bun-debug.exe" by default
bun run test

# Run an individual test file:
bun-debug test node\fs
bun-debug test "C:\bun\test\js\bun\resolve\import-meta.test.js"

Troubleshooting

.rc file fails to build

llvm-rc.exe is odd; don't use it. Use rc.exe instead: make sure you are in a Visual Studio dev terminal, and check rc /? to confirm it is Microsoft Resource Compiler.

failed to write output 'bun-debug.exe': permission denied

You cannot overwrite bun-debug.exe while it is open. You likely have a running instance, maybe in the VS Code debugger.

Cross-compiling from Linux

You can also build Windows binaries (both x64 and arm64) on a Linux host. The build uses the host LLVM's clang-cl, lld-link, llvm-lib and llvm-rc (part of every LLVM distribution). For headers and import libraries, the build also uses an "xwin splat" of the MSVC CRT/STL and Windows SDK.

Prerequisites

1. The same LLVM version a native build uses (pins.llvm in scripts/build/ci-images/spec.ts), installed so that clang-cl, lld-link, llvm-lib and llvm-rc are available. On Debian/Ubuntu, apt.llvm.org packages provide all of them.
2. nasm (only needed for Windows x64; BoringSSL's x64 assembly is NASM syntax).
3. Rust std for the Windows targets (rust-toolchain.toml lists them; rustup target add x86_64-pc-windows-msvc aarch64-pc-windows-msvc if missing).
4. A Windows sysroot: an xwin splat of the MSVC CRT and Windows SDK laid out like a Visual Studio install. Downloading these components means accepting Microsoft's license terms for them.

cargo install xwin # or download a release binary
xwin --accept-license --arch x86_64,aarch64 --sdk-version 10.0.26100 --crt-version 14.44.17.14 splat \
  --use-winsysroot-style --preserve-ms-arch-notation --include-debug-libs \
  --output /opt/winsysroot
# clang-cl/lld-link look up SDK paths as "Include"/"Lib"; the splat writes
# them lowercase, so alias both spellings (needs the same privileges as the
# splat — configure creates these itself when the directory is writable).
ln -s include "/opt/winsysroot/Windows Kits/10/Include"
ln -s lib "/opt/winsysroot/Windows Kits/10/Lib"

The build looks for the sysroot at /opt/winsysroot (or /opt/xwin) automatically. If the sysroot is elsewhere, set WINDOWS_SYSROOT=<path> or pass --winsysroot=<path>. A user-writable path also lets configure manage the aliases for you. Configure validates the splat at the start of every cross build. CI agents bake the same splat into their images (the windowsSysroot tool of scripts/build/ci-images/spec.ts); when an agent doesn't have one, the build fetches it into its cache dir at configure time.

Building

# Debug builds
bun run build --profile=windows-x64
bun run build --profile=windows-arm64

# Release builds
bun run build --profile=windows-x64-release
bun run build --profile=windows-arm64-release

Output lands in build/debug-windows-x64/bun-debug.exe, build/release-windows-aarch64/bun-profile.exe + bun.exe, and so on. Equivalent raw flags: bun run build --os=windows --arch=aarch64.

The build does not run cross-compiled executables on the host (it skips the --revision smoke test), so test them on a Windows machine or under Wine.

LTO

x64 release cross builds use ThinLTO with cross-language (Rust↔C++) LTO, like every release build (--lto=off for faster relinks):

• Bun's C/C++ compiles with -flto=thin
• rustc emits LLVM bitcode (-Clinker-plugin-lto)
• the bun-webkit-windows-amd64-lto ThinLTO prebuilt is the WebKit that gets linked
• everything links with LLVM's lld-link, which reads both compilers' bitcode: the build requires clang's LLVM and rustc's to be the same major version

There is no LTO for arm64, because there is no -lto WebKit prebuilt: LLVM's CodeView emitter can't handle ARM64 NEON tuple registers during LTO codegen.