Building Custom k6 Binaries

Use xk6 to build custom k6 binaries with extensions using Go or Docker

To use extensions that aren’t available through automatic resolution, or to bundle multiple extensions together, build a custom k6 binary using xk6.

You can build custom binaries locally with Go or use the xk6 Docker image.

Build with Go and xk6

Building locally gives you direct control over the build process and is ideal for development.

Before you start

1. Install Go

   Set up Go (version 1.19 or higher) and ensure go version returns the correct version.

2. Install Git

   Install Git for downloading extension sources.

3. Install xk6

   Install xk6 with a single command:

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

Verify installation:

Linux/Mac

which xk6

where xk6

If the command doesn’t return a path, ensure $GOPATH/bin is in your $PATH. See the Go documentation for details.

Build your first extension

Once installed, build a k6 binary with extensions using the xk6 build command:

xk6 build latest \
  --with github.com/grafana/xk6-sql@v0.0.1 \
  --with github.com/grafana/xk6-output-prometheus-remote

This creates a k6 binary in the current directory with the xk6-sql and xk6-output-prometheus-remote extensions.

Output:

... [INFO] Build environment ready
... [INFO] Building k6
... [INFO] Build complete: ./k6

xk6 has now produced a new k6 binary which may be different than the command on your system path!
Be sure to run './k6 run <SCRIPT_NAME>' from the current directory.

Command breakdown

The xk6 command syntax:

xk6 build [<k6_version>]
    [--output <file>]
    [--with <module[@version][=replacement]>...]
    [--replace <module=replacement>...]

Flags:
  --output   specifies the new binary name [default: 'k6']
  --replace  enables override of dependencies for k6 and extensions [default: none]
  --with     the extension module to be included in the binary [default: none]

The --replace flag should be considered an advanced feature to be avoided unless required.

Understanding the build command

From the example above:

• Version: latest builds using the latest k6 source code. Consider using a stable release version (e.g., v0.45.1) as a best practice.
• Extension modules: Each --with flag specifies a full GitHub URI. Without a version, it defaults to latest. Lock versions like xk6-sql@v0.0.1 for stability.
• Output location: Without --output, the binary is named k6 in the current directory. Use --output k6-extended for a custom name or --output /tmp/k6 for a different location.

Verify your build:

./k6 version

Output shows the k6 version and included extensions:

k6 v0.45.1 ((devel), go1.20.1, linux/amd64)
Extensions:
  github.com/grafana/xk6-output-prometheus-remote v0.3.0, xk6-prometheus-remote [output]
  github.com/grafana/xk6-sql v0.0.1, k6/x/sql [js]

Build from a local repository

If you’ve cloned an extension repository locally and want to use that version:

cd /path/to/xk6-sql
xk6 build --with github.com/grafana/xk6-sql=.

The . tells xk6 to use the current directory as the replacement for the module.

Run your extended binary

Now run test scripts using the bundled extensions:

./k6 run my-script.js

Be sure to specify ./k6 on Linux/Mac to use the local binary, otherwise the system may execute a different k6 on your PATH. Windows shells search the current directory by default.

Build with Docker

Using the xk6 Docker image simplifies the process by avoiding local Go setup.

This guide covers creating a custom k6 binary using Docker. To create a Docker image with a custom k6 binary, refer to the Using modules with Docker documentation.

Build your first extension

Build a custom k6 binary with the latest versions of k6 and extensions:

Linux

docker run --rm -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" grafana/xk6 build \
  --with github.com/mostafa/xk6-kafka \
  --with github.com/grafana/xk6-output-influxdb

docker run --rm -e GOOS=darwin -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" \
  grafana/xk6 build \
  --with github.com/mostafa/xk6-kafka \
  --with github.com/grafana/xk6-output-influxdb

docker run --rm -e GOOS=windows -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" `
  grafana/xk6 build --output k6.exe `
  --with github.com/mostafa/xk6-kafka `
  --with github.com/grafana/xk6-output-influxdb

docker run --rm -e GOOS=windows -v "%cd%:/xk6" ^
  grafana/xk6 build --output k6.exe ^
  --with github.com/mostafa/xk6-kafka ^
  --with github.com/grafana/xk6-output-influxdb

This creates a k6 (or k6.exe) binary in the current working directory.

Build with specific versions

To build with concrete versions (k6 v0.45.1, xk6-kafka v0.19.1, xk6-output-influxdb v0.4.1):

Linux

docker run --rm -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" grafana/xk6 build v0.45.1 \
  --with github.com/mostafa/xk6-kafka@v0.19.1 \
  --with github.com/grafana/xk6-output-influxdb@v0.4.1

docker run --rm -e GOOS=darwin -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" \
  grafana/xk6 build v0.45.1 \
  --with github.com/mostafa/xk6-kafka@v0.19.1 \
  --with github.com/grafana/xk6-output-influxdb@v0.4.1

docker run --rm -e GOOS=windows -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" `
  grafana/xk6 build v0.45.1 --output k6.exe `
  --with github.com/mostafa/xk6-kafka@v0.19.1 `
  --with github.com/grafana/xk6-output-influxdb@v0.4.1

Docker command breakdown

The Docker-specific part of the command:

docker run --rm -u "$(id -u):$(id -g)" -v "${PWD}:/xk6"

• --rm - Container is destroyed after the build completes
• -u - Specifies user and group IDs so the binary has the same permissions as the host user
• -v - Mounts the current directory inside the container so the binary can be written to it

For Windows and macOS, add the target OS:

-e GOOS=<target os>

The remainder follows standard xk6 command syntax.

Verify the build

Run the version command to check your build:

Linux/macOS

./k6 version

k6.exe version

Output:

k6 v0.45.1 ((devel), go1.20.1, darwin/amd64)
Extensions:
  github.com/grafana/xk6-output-influxdb v0.4.1, xk6-influxdb [output]
  github.com/mostafa/xk6-kafka v0.19.1, k6/x/kafka [js]

Run your extended binary

Linux/macOS

./k6 run my-script.js

k6.exe run my-script.js

On Linux/Mac, specify ./k6 to use the local binary. Windows shells search the current directory by default.

Common build scenarios

Multiple extensions

Bundle multiple extensions in one binary:

xk6 build v0.45.1 \
  --with github.com/grafana/xk6-sql@v0.0.1 \
  --with github.com/grafana/xk6-output-prometheus-remote \
  --with github.com/mostafa/xk6-kafka@v0.19.1 \
  --with github.com/grafana/xk6-output-influxdb@v0.4.1

Output to specific location

xk6 build --output ~/bin/k6-custom \
  --with github.com/grafana/xk6-sql@v0.0.1

Latest development version

xk6 build latest \
  --with github.com/grafana/xk6-disruptor@latest

Using latest builds from the bleeding edge. Use stable release versions for production.

Troubleshooting

If you encounter issues:

• Go environment: Ensure go version works and $GOPATH/bin is in your $PATH
• xk6 not found: Verify installation with which xk6 or where xk6
• Build errors: Check extension compatibility with your k6 version
• Docker permissions: On Linux, use -u "$(id -u):$(id -g)" to avoid permission issues

For more help, search the k6 Community Forum.

Next steps

Create Extensions

Build your own k6 extensions

Explore Extensions

Find extensions for your use case

Protocol Extensions

Use MQTT, Redis, and SQL extensions

xk6 Repository

View xk6 source and documentation