Skip to main content

​
Installation methods

workerd can be installed in two ways:
  1. Via npm (recommended): Quick installation using prebuilt binaries
  2. Build from source: Full control and latest features

​
Supported platforms

workerd is tested and supported on:
  • Linux: x86-64 and arm64 architectures
  • macOS: x86-64 and arm64 architectures (macOS 13.5 or higher)
  • Windows: x86-64 architecture
On other POSIX systems supported by V8, workerd may work but requires additional configuration.

​
Install via npm

The easiest way to get started with workerd is using the prebuilt binaries distributed through npm.
1

Install using npx

You can run workerd directly without installation:
npx workerd --help
This downloads and runs the appropriate binary for your platform.
2

Or install globally

For frequent use, install workerd globally:
npm install -g workerd
Then run it directly:
workerd serve config.capnp
3

Verify installation

Check that workerd is working:
workerd --version
You should see output like workerd 1.20240101.0.

​
System requirements

Prebuilt binaries require:
  • glibc 2.35 or higher (included in Ubuntu 22.04, Debian Bookworm)
  • x86_64 CPU with SSE4.2 and CLMUL extensions, or arm64 CPU with CRC extension
Most modern CPUs support these extensions.

​
Build from source

Building workerd from source gives you the latest features and full control over the build.

​
Prerequisites

Install the required dependencies:
# On Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
  clang-19 \
  libc++-19-dev \
  libc++abi-19-dev \
  lld-19 \
  python3 \
  python3-distutils \
  tcl8.6
Requirements:
  • Clang 19+ (earlier versions may work but aren’t officially supported)
  • libc++ 19+
  • LLD 19+
  • Python 3 with distutils
  • Tcl 8.6
  • Bazelisk (recommended) or Bazel
If clang is installed as clang-<version>, create a symlink:
sudo ln -s /usr/bin/clang-19 /usr/local/bin/clang
Or specify it when building:
bazel build --action_env=CC=clang-19 //src/workerd/server:workerd

​
Build workerd

1

Clone the repository

git clone https://github.com/cloudflare/workerd.git
cd workerd
2

Build with Bazel

Build the workerd binary:
bazel build //src/workerd/server:workerd
For a release build with optimizations:
bazel build --config=release //src/workerd/server:workerd
For an even faster build with link-time optimization (requires recent clang):
bazel build --config=thin-lto //src/workerd/server:workerd
3

Locate the binary

The compiled binary is at:
bazel-bin/src/workerd/server/workerd
You can run it directly:
./bazel-bin/src/workerd/server/workerd --help
4

Optional: Install system-wide

Copy the binary to your PATH:
# Linux/macOS
sudo cp bazel-bin/src/workerd/server/workerd /usr/local/bin/

# Or create a symlink
sudo ln -s $(pwd)/bazel-bin/src/workerd/server/workerd /usr/local/bin/workerd

​
Troubleshooting build issues

If you installed dependencies after a failed build attempt, Bazel may have cached the old configuration:
# Try resyncing toolchains
bazel fetch --configure --force

# If that doesn't work, clean the cache
bazel clean --expunge
Then try building again.
Ensure you’re using clang 19 or higher:
clang --version
If you have multiple versions installed, specify the version:
bazel build --action_env=CC=clang-19 //src/workerd/server:workerd
Bazel can use a lot of memory. Limit parallel jobs:
bazel build --jobs=2 //src/workerd/server:workerd

​
Development tools

For development, consider installing additional tools:

​
Just command runner

The workerd repository uses just for common tasks: 
# Install just
cargo install just

# Or with package managers
brew install just  # macOS

# Then use shortcuts
just build   # Build workerd
just test    # Run tests
just format  # Format code
```bash

### Wrangler integration

To use your local workerd build with [Wrangler](https://developers.cloudflare.com/workers/wrangler/):

```bash
export MINIFLARE_WORKERD_PATH="/path/to/workerd/bazel-bin/src/workerd/server/workerd"
wrangler dev

​
Next steps

Quick start

Create your first workerd application

Configuration

Learn about workerd’s configuration format

Examples

Browse sample configurations

Development guide

Deep dive into building and developing workerd

Build docs developers (and LLMs) love

Get started for freeTalk to us