Skip to main content
This guide will walk you through building workerd from source on Linux, macOS, and Windows.

​
Prerequisites

​
All platforms

  • Bazelisk (recommended) - automatically downloads and uses the correct Bazel version
  • Or Bazel installed manually

​
Linux

You need clang/LLVM toolchain version 19 or higher: 
sudo apt-get install -y clang-19 libc++-19-dev libc++abi-19-dev lld-19
Additional dependencies: 
sudo apt-get install -y python3 python3-distutils tcl8.6
If clang is installed as clang-<version>, create a symlink named clang in your PATH, or use --action_env=CC=clang-<version> on bazel command lines.

​
macOS

  • Xcode 16.3 (available on macOS 15 and higher)
  • Homebrew’s tcl-tk package:
brew install tcl-tk
Building with just the Xcode Command Line Tools is not actively tested, but should work.

​
Windows

1

Install dependencies

Install App Installer from the Microsoft Store for the winget package manager.Run from an administrator prompt:
tools/windows/install-deps.bat
This installs bazelisk, LLVM, and other required dependencies.
2

Configure Bazel

Add to .bazelrc in your user directory:
startup --output_user_root=C:/tmp
3

Set up environment

When developing at the command line, run tools/windows/bazel-env.bat in your shell first to select tools and Windows SDK versions before running bazel.

​
Building workerd

​
Debug build

Build workerd in debug mode: 
bazel build //src/workerd/server:workerd
The compiled binary will be at: 
bazel-bin/src/workerd/server/workerd

​
Release build

For an optimized release build: 
bazel build //src/workerd/server:workerd --config=release

​
High-performance build

For the best performance with thin LTO (Link Time Optimization): 
bazel build --config=thin-lto //src/workerd/server:workerd
This requires a fairly recent clang installation.

​
Using Just commands

The project includes a justfile with convenient shortcuts. Install Just: 
cargo install just
Then use these commands: 
just build
# or
just b

​
Troubleshooting

​
Dependency installation issues

If you install dependencies after running a build, you need to resync cached toolchains: 
bazel fetch --configure --force
If that fails, clean the cache: 
bazel clean --expunge

​
Visual Studio Code

You can also build from within Visual Studio Code. See the VSCode guide for setup instructions.

​
Next steps

Testing

Learn how to run tests

Debugging

Set up debugging tools

Build docs developers (and LLMs) love

Get started for freeTalk to us