Building custom k6.exe Binaries on Windows using xk6

If you need to load test protocols beyond standard HTTP, such as database query structures or Prometheus metrics streaming, the default k6 binary is not going to work. As we discussed in our architectural deep dive, k6's execution capabilities must be extended by compiling a customized executable using the xk6 package compiler. While Linux users can easily run these compiles inside containerized CI environments, compiling custom executables locally on Windows requires setting up a local compilation toolchain.

Let us walk through the step-by-step process of preparing your Windows environment and compiling a custom k6.exe binary.

Step 1: Install the Go and Git Prerequisites

Because k6 is written in Go, compiling custom binaries requires a local Go runtime environment, along with Git to pull down the source modules. Make sure both are installed and registered in your system PATH:

Go Toolchain: Download and execute the official Windows MSI installer package from go.dev/dl. Open a fresh terminal and verify the installation by running go version.
Git for Windows: Download and execute the official installer from git-scm.com. Ensure you check the option that adds the git executable to your system's PATH variable, and verify it by running git --version in your terminal.

Step 2: Install xk6 Globally

With Go and Git fully configured, you can now install the xk6 package manager globally. This command fetches the compiler driver source, builds it, and drops it into your user Go bin path:

go install go.k6.io/xk6/cmd/xk6@latest

Ensure that your GOPATH\bin folder (typically C:\Users\YourUser\go\bin) is added to your user environment variables so your terminal can locate the xk6 executable.

Step 3: Compile Your Custom k6.exe Binary

You are now ready to run the compilation. To write multi-line command formatting inside Windows PowerShell, use the backtick symbol (`) as the line continuation character. Execute this compilation command to generate a customized k6.exe binary containing extensions for direct SQL connectivity and Prometheus remote write output:

# Run xk6 compiler driver to build a customized Windows executable
xk6 build latest `
  --output .\k6-extended.exe `
  --with github.com/grafana/xk6-sql@latest `
  --with github.com/grafana/xk6-output-prometheus-remote@latest

The compiler driver generates a temporary main file, pulls down the Go source modules, maps PascalCase method names into camelCase JavaScript APIs, and compiles a self-contained k6-extended.exe binary in your workspace directory.

You can now invoke your customized local engine to run your tests by executing:

.\k6-extended.exe run script.js

By establishing this local Go and Git compiler chain on your Windows workstation, you can compile and validate customized binaries in seconds, bypassing the bottleneck of pipeline build queues.

To learn how to structure an enterprise-grade testing framework around this custom executable, see Architecting an Enterprise k6 Framework on Windows. If you want to see how to run tests and capture compressed HTML outputs, check out k6 Workload Execution and static Gzip HTML Report Generation on Windows. To understand the underlying Go-to-JavaScript reflection mechanism, read xk6 Architecture: Extending the k6 Runtime with Custom Go Bindings.

k6.wiki