Add Windows ARM64 build and release support

threepointone · threepointone · commit 61c282d59d0b · 2026-04-02T20:14:04.000+01:00
Add end-to-end support for building, testing, and releasing workerd on
Windows ARM64 (aarch64-pc-windows-msvc). This enables `npm install workerd`
to work natively on Windows ARM64 devices (e.g. Snapdragon laptops) via
the new @cloudflare/workerd-windows-arm64 package.

Bazel build system:
- Define arm64_windows-clang-cl platform in BUILD.bazel
- Add build:windows_arm64 config overriding the toolchain and execution
  platform from x64 to ARM64
- Add build:release_windows_arm64 composing release_windows + windows_arm64
- Add build:ci-windows-arm64 for CI release builds

Rust toolchain:
- Register aarch64-pc-windows-msvc in RUST_TARGET_TRIPLES so rules_rust
  downloads and configures a Rust toolchain for the new target
- Add the triple to supported_platform_triples in crates_vendor so the
  Cargo dependency graph resolves for Windows ARM64
- Add win_arm64 config_setting_group and wire cargo-bazel to use the x64
  binary under WoW64 emulation (no native ARM64 build available)

Host tools:
- Add @bazel_tools//src/conditions:windows_arm64 entries to wasm-tools
  and clang-tidy selects, falling back to x64 binaries under emulation

NPM distribution:
- Create npm/workerd-windows-arm64/ package (os: win32, cpu: arm64)
- Add "win32 arm64 LE" to knownPackages in node-platform.ts
- Add @cloudflare/workerd-windows-arm64 to optionalDependencies in the
  workerd meta-package and build-shim-package.mjs

CI/CD:
- Add windows-arm64 build matrix entry in release.yml using the
  windows-11-arm GitHub Actions runner
- Add windows-arm64 upload-artifacts entry for release asset publishing
  and npm per-arch package publishing
- Add windows-arm64 to test.yml matrix (debug builds excluded, matching
  the x64 Windows exclusion for disk space reasons)

Note: the @local_config_cc toolchain name for ARM64 Windows is
auto-generated by Bazel based on what it discovers on the host. If the
first CI run fails with a toolchain resolution error, query
@local_config_cc//:all on the runner to find the correct label.

Made-with: Cursor
diff --git a/.bazelrc b/.bazelrc
@@ -346,6 +346,12 @@ build:windows --enable_runfiles
 build:windows --extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows-clang-cl
 build:windows --extra_execution_platforms=//:x64_windows-clang-cl
 
+# Windows ARM64 overrides: use the ARM64 platform instead of x64. The toolchain name is
+# auto-generated by local_config_cc – if this doesn't match what Bazel detects on the ARM64
+# runner, query @local_config_cc//:all to find the correct name.
+build:windows_arm64 --extra_toolchains=@local_config_cc//:cc-toolchain-arm64_windows-clang-cl
+build:windows_arm64 --extra_execution_platforms=//:arm64_windows-clang-cl
+
 # The Windows fastbuild bazel configuration is broken in that it necessarily generates PDB debug
 # information while the Linux and macOS toolchains only compile with debug information in the dbg
 # configuration or when requested with the -g flag. This causes huge increases in compile time and
@@ -435,6 +441,9 @@ build:release_windows --per_file_copt="src/workerd/server/container-client"@/cla
 # Work around Windows test failures in rpc-related tests
 build:release_windows --per_file_copt=src/workerd/io/worker-interface@/clang:-fno-inline
 
+build:release_windows_arm64 --config=release_windows
+build:release_windows_arm64 --config=windows_arm64
+
 build:windows --cxxopt='/std:c++23preview' --host_cxxopt='/std:c++23preview'
 build:windows --copt='/D_CRT_USE_BUILTIN_OFFSETOF' --host_copt='/D_CRT_USE_BUILTIN_OFFSETOF'
 build:windows --copt='/DWIN32_LEAN_AND_MEAN' --host_copt='/DWIN32_LEAN_AND_MEAN'
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -104,6 +104,11 @@ jobs:
             image: windows-2025-16core
             bazel-config: release_windows
             target-arch: X64
+          - title: windows-arm64
+            os-name: Windows
+            image: windows-11-arm
+            bazel-config: release_windows_arm64
+            target-arch: ARM64
     name: build (${{ matrix.title }})
     uses: './.github/workflows/_bazel.yml'
     with:
@@ -129,8 +134,6 @@ jobs:
     strategy:
       matrix:
         arch: [linux-64, darwin-64, windows-64]
-        # This variable itself is unused, but allows us to set up two macOS builds. arm64 builds for
-        # other platforms will be supported later, then we'll list both architectures here.
         cpu: [X64]
         include:
           - arch: linux-64
@@ -145,6 +148,9 @@ jobs:
             cpu: ARM64
           - arch: windows-64
             name: Windows-X64
+          - arch: windows-arm64
+            name: Windows-ARM64
+            cpu: ARM64
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v6
@@ -157,15 +163,15 @@ jobs:
           name: ${{ matrix.name }}-binary
           path: /tmp
       # Set execute permissions before compressing the binary
-      - if: matrix.arch != 'windows-64'
+      - if: ${{ !contains(matrix.arch, 'windows') }}
         run: chmod +x /tmp/workerd
       - name: Compress release binary
         run: |
           # As of release v1.20230404.0 the Linux x64 binary after debug_strip is 65.8 MB,
           # 21.0 MB with gzip and 17.3 MB with brotli -9. Use gzip as a widely supported format
           # which still produces an acceptable compressed size.
-          gzip -9N -k /tmp/workerd${{ matrix.arch == 'windows-64' && '.exe' || '' }}
-      - run: mv /tmp/workerd${{ matrix.arch == 'windows-64' && '.exe' || '' }}.gz /tmp/workerd-${{ matrix.arch }}.gz
+          gzip -9N -k /tmp/workerd${{ contains(matrix.arch, 'windows') && '.exe' || '' }}
+      - run: mv /tmp/workerd${{ contains(matrix.arch, 'windows') && '.exe' || '' }}.gz /tmp/workerd-${{ matrix.arch }}.gz
       # Upload compressed release binaries – one set of artifacts is sufficient with gzip being
       # widely supported
       - name: Upload Release Assets
@@ -190,7 +196,7 @@ jobs:
           WORKERD_VERSION: ${{ needs.version.outputs.version }}
           LATEST_COMPATIBILITY_DATE: ${{ needs.version.outputs.date }}
       - run: mkdir npm/workerd-${{ matrix.arch }}/bin
-      - run: cp /tmp/workerd${{ matrix.arch == 'windows-64' && '.exe' || '' }} npm/workerd-${{ matrix.arch }}/bin/workerd${{ matrix.arch == 'windows-64' && '.exe' || '' }}
+      - run: cp /tmp/workerd${{ contains(matrix.arch, 'windows') && '.exe' || '' }} npm/workerd-${{ matrix.arch }}/bin/workerd${{ contains(matrix.arch, 'windows') && '.exe' || '' }}
       - run: echo '//registry.npmjs.org/:_authToken=${NPM_TOKEN}' > npm/workerd-${{ matrix.arch }}/.npmrc
       - run: cd npm/workerd-${{ matrix.arch }} && npm publish --access public --tag ${{ startsWith(needs.version.outputs.version, '0') && 'beta' || 'latest'}}
         env:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -37,6 +37,7 @@ jobs:
             { name: linux-arm, arch: ARM64, image: ubuntu-22.04-arm-16core },
             { name: macOS, arch: ARM64, image: macos-15-xlarge, use_lld: true },
             { name: windows, arch: X64, image: windows-2025-16core },
+            { name: windows-arm64, arch: ARM64, image: windows-11-arm },
           ]
         config: [
             # Default build: no suffix or additional bazel arguments
@@ -57,6 +58,8 @@ jobs:
         exclude:
           - os: { name: windows, arch: X64, image: windows-2025-16core }
             config: { suffix: -debug }
+          - os: { name: windows-arm64, arch: ARM64, image: windows-11-arm }
+            config: { suffix: -debug }
           # due to resource constraints, exclude the macOS and x64 Linux debug runners for now.
           # linux-asan and arm64 linux-debug should provide sufficient coverage for building in the
           # debug configuration.
diff --git a/BUILD.bazel b/BUILD.bazel
@@ -62,6 +62,15 @@ platform(
     ],
 )
 
+platform(
+    name = "arm64_windows-clang-cl",
+    constraint_values = [
+        "@platforms//cpu:aarch64",
+        "@platforms//os:windows",
+        "@bazel_tools//tools/cpp:clang-cl",
+    ],
+)
+
 # Used for cross-compilation
 platform(
     name = "macOS_x86",
diff --git a/RELEASE.md b/RELEASE.md
@@ -8,4 +8,4 @@ The primary distribution channel for `workerd` right now is through `npm`. We us
 
 ## Cutting Releases
 
-This is pretty simple, and completely automatic—every time the date in [release-version.txt](src/workerd/io/release-version.txt) changes, a new release is generated, along with the built binaries for `linux-64`, `linux-arm64`, `darwin-64`, `darwin-arm64` and `windows-64`. The types will also be generated and published automatically. This is governed by the [release.yml](.github/workflows/release.yml) GitHub Action.
+This is pretty simple, and completely automatic—every time the date in [release-version.txt](src/workerd/io/release-version.txt) changes, a new release is generated, along with the built binaries for `linux-64`, `linux-arm64`, `darwin-64`, `darwin-arm64`, `windows-64` and `windows-arm64`. The types will also be generated and published automatically. This is governed by the [release.yml](.github/workflows/release.yml) GitHub Action.
diff --git a/build/ci.bazelrc b/build/ci.bazelrc
@@ -88,12 +88,15 @@ test:ci-macOS --spawn_strategy=local
 build:ci-windows --config=release_windows
 build:ci-windows-debug --config=debug
 
+build:ci-windows-arm64 --config=release_windows_arm64
+
 # Some tests (like Python import tests) take a long time to run, especially when debug is enabled
 # For that reason, we only run them in the default configuration for each platform to minimize
 # effect on CI pipeline runtime.
 test:ci-linux --test_size_filters=
 test:ci-macOS --test_size_filters=
 test:ci-windows --test_size_filters=
+test:ci-windows-arm64 --test_size_filters=
 
 # Run container tests on Linux CI
 test:ci-linux --test_tag_filters=-off-by-default,-requires-fuzzilli
diff --git a/build/deps/rust.MODULE.bazel b/build/deps/rust.MODULE.bazel
@@ -8,6 +8,8 @@ RUST_TARGET_TRIPLES = [
     "x86_64-apple-darwin",
     # Add support for macOS rosetta
     "aarch64-unknown-linux-gnu",
+    # Add support for Windows ARM64
+    "aarch64-pc-windows-msvc",
 ]
 
 # rules_rust
@@ -36,6 +38,7 @@ rust.toolchain(
         "x86_64-pc-windows-msvc": ["-Ctarget-feature=+sse4.2"],
         "aarch64-unknown-linux-gnu": ["-Ctarget-feature=+crc"],
         # No options needed for aarch64-apple-darwin: CRC feature is enabled by default.
+        # No options needed for aarch64-pc-windows-msvc: CRC feature is enabled by default on ARM64.
     },
     extra_target_triples = RUST_TARGET_TRIPLES,
     rustfmt_version = RUST_NIGHTLY_VERSION,
diff --git a/deps/rust/BUILD.bazel b/deps/rust/BUILD.bazel
@@ -45,12 +45,22 @@ selects.config_setting_group(
     ],
 )
 
+selects.config_setting_group(
+    name = "win_arm64",
+    match_all = [
+        "@platforms//os:windows",
+        "@platforms//cpu:aarch64",
+    ],
+)
+
 CARGO_BAZEL = select({
     ":linux_x64": "@cargo_bazel_linux_x64//file:downloaded",
     ":linux_arm64": "@cargo_bazel_linux_arm64//file:downloaded",
     ":macos_x64": "@cargo_bazel_macos_x64//file:downloaded",
     ":macos_arm64": "@cargo_bazel_macos_arm64//file:downloaded",
     ":win_x64": "@cargo_bazel_win_x64//file:downloaded.exe",
+    # x64 cargo-bazel runs under emulation on Windows ARM64
+    ":win_arm64": "@cargo_bazel_win_x64//file:downloaded.exe",
 })
 
 # Generates a repository containing all the crates we reference from our
@@ -82,6 +92,7 @@ crates_vendor(
         "aarch64-unknown-linux-gnu",
         "x86_64-unknown-linux-gnu",
         "x86_64-pc-windows-msvc",
+        "aarch64-pc-windows-msvc",
     ],
 )
 
diff --git a/npm/lib/node-platform.ts b/npm/lib/node-platform.ts
@@ -17,6 +17,7 @@ export const knownPackages: Record<string, string> = {
   "darwin x64 LE": "@cloudflare/workerd-darwin-64",
   "linux arm64 LE": "@cloudflare/workerd-linux-arm64",
   "linux x64 LE": "@cloudflare/workerd-linux-64",
+  "win32 arm64 LE": "@cloudflare/workerd-windows-arm64",
   "win32 x64 LE": "@cloudflare/workerd-windows-64",
 };
 
diff --git a/npm/scripts/build-shim-package.mjs b/npm/scripts/build-shim-package.mjs
@@ -17,6 +17,7 @@ function buildNeutralLib() {
     '@cloudflare/workerd-darwin-64': process.env.WORKERD_VERSION,
     '@cloudflare/workerd-linux-arm64': process.env.WORKERD_VERSION,
     '@cloudflare/workerd-linux-64': process.env.WORKERD_VERSION,
+    '@cloudflare/workerd-windows-arm64': process.env.WORKERD_VERSION,
     '@cloudflare/workerd-windows-64': process.env.WORKERD_VERSION,
   };
   fs.writeFileSync(pjPath, JSON.stringify(package_json, null, 2) + '\n');
diff --git a/npm/workerd-windows-arm64/package.json b/npm/workerd-windows-arm64/package.json
@@ -0,0 +1,17 @@
+{
+  "name": "@cloudflare/workerd-windows-arm64",
+  "description": "👷 workerd for Windows ARM64, Cloudflare's JavaScript/Wasm Runtime",
+  "repository": "https://github.com/cloudflare/workerd",
+  "license": "Apache-2.0",
+  "preferUnplugged": false,
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "win32"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "version": "1.20220926.0"
+}
diff --git a/npm/workerd/package.json b/npm/workerd/package.json
@@ -18,6 +18,7 @@
     "@cloudflare/workerd-darwin-64": "1.20220926.0",
     "@cloudflare/workerd-linux-arm64": "1.20220926.0",
     "@cloudflare/workerd-linux-64": "1.20220926.0",
+    "@cloudflare/workerd-windows-arm64": "1.20220926.0",
     "@cloudflare/workerd-windows-64": "1.20220926.0"
   },
   "license": "Apache-2.0"
diff --git a/tools/BUILD.bazel b/tools/BUILD.bazel
@@ -51,6 +51,8 @@ native_binary(
             "@bazel_tools//src/conditions:darwin_arm64": "@wasm_tools_macos_arm64//:wasm-tools",
             "@bazel_tools//src/conditions:darwin_x86_64": "@wasm_tools_macos_x64//:wasm-tools",
             "@bazel_tools//src/conditions:windows_x64": "@wasm_tools_windows_x64//:wasm-tools.exe",
+            # x64 binary runs under emulation on Windows ARM64
+            "@bazel_tools//src/conditions:windows_arm64": "@wasm_tools_windows_x64//:wasm-tools.exe",
         },
     ),
     out = "wasm-tools",
@@ -65,6 +67,8 @@ native_binary(
             "@bazel_tools//src/conditions:linux_aarch64": "@clang_tidy_linux_arm64//file:downloaded",
             "@bazel_tools//src/conditions:darwin_arm64": "@clang_tidy_darwin_arm64//file:downloaded",
             "@bazel_tools//src/conditions:windows_x64": "@clang_tidy_windows_amd64//file:downloaded",
+            # x64 binary runs under emulation on Windows ARM64
+            "@bazel_tools//src/conditions:windows_arm64": "@clang_tidy_windows_amd64//file:downloaded",
         },
     ),
     out = "clang_tidy",

Original file line number	Diff line number	Diff line change
@@ -8,4 +8,4 @@ The primary distribution channel for `workerd` right now is through `npm`. We us
`8`	`8`
`9`	`9`	`## Cutting Releases`
`10`	`10`
`11`		-This is pretty simple, and completely automatic—every time the date in [release-version.txt](src/workerd/io/release-version.txt) changes, a new release is generated, along with the built binaries for `linux-64`, `linux-arm64`, `darwin-64`, `darwin-arm64` and `windows-64`. The types will also be generated and published automatically. This is governed by the [release.yml](.github/workflows/release.yml) GitHub Action.
	`11`	+This is pretty simple, and completely automatic—every time the date in [release-version.txt](src/workerd/io/release-version.txt) changes, a new release is generated, along with the built binaries for `linux-64`, `linux-arm64`, `darwin-64`, `darwin-arm64`, `windows-64` and `windows-arm64`. The types will also be generated and published automatically. This is governed by the [release.yml](.github/workflows/release.yml) GitHub Action.