Run a test with extensions on Grafana Labs

Build a k6 binary using Go

Mon, 21 Sep 2026 15:16:28 +0000

Build a k6 binary using Go

To use an extension that you found on the Extension page or the xk6 GitHub topic, you need to build a binary using Go.

Note
Not interested in setting up a Go environment? You can use Docker instead.

Before you start

Set up Go and Git.
Make sure that your $PATH environment variable is updated so that go version returns the correct version.

Installing xk6

Given the prerequisite Go setup, installing xk6 itself requires only the following command:

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

To confirm your installation, run which xk6 on Linux and Mac, or where xk6 on Windows. Make sure the command returns a valid path.

If not, check that you’ve correctly defined the$GOPATH environment variable and that $GOPATH/bin is in your $PATH. See the Go documentation for details.

Building your first extension

Once installed, building a k6 binary with one or more extensions can be done with the xk6 build command as follows:

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

Once completed, the current directory contains your newly built k6 binary with the xk6-sql and xk6-output-prometheus-remote extensions.

... [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 '...' directory.

Breaking down the xk6 command

From the xk6 documentation, the command-line usage is as follows:

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 use of --replace should be considered an advanced feature to be avoided unless required.

Referring back to our executed command, note that:

We specify the version as latest, which is also the default if we hadn’t supplied a version. latest means that we’ll build using the latest source code for k6. Consider using a stable release version as a best practice unless you genuinely want the bleeding edge.
With each --with, we specified a full GitHub URI for the extension repository. If not specifying a version, the default is latest once again. Check your extension repository for stable release versions, if available, to lock in your version as we’ve done with xk6-sql@v0.0.1.
We did not use the --output option; therefore, our new binary is k6 within the current directory. Had we used --output k6-extended, our binary would be named k6-extended within the current directory. If a directory is specified, then the new binary would be k6 within that directory. If a path to a non-existent file, e.g. /tmp/k6-extended, this will be the path and filename for the binary.

Running ./k6 version should show your build is based upon the appropriate version.

Building from a local repository

Suppose now you’ve cloned the xk6-sql repository and want the local version included in your custom binary? From the cloned directory, we would then use:

--with github.com/grafana/xk6-sql=.

Based upon the command usage described in the previous section, this tells xk6 to use the current directory as the replacement for the module.

Running your extended binary

Now that we have our newly built k6 binary, we can run scripts using the functionalities of the bundled extensions.

./k6 run my-script.js

Be sure to specify the binary just built in the current directory as ./k6, or else Linux/Mac could execute another k6 binary on your system path. Windows shells will first search for the binary in the current directory by default.

Build a k6 binary using Docker

Mon, 21 Sep 2026 15:16:28 +0000

Build a k6 binary using Docker

Using the xk6 Docker image can simplify the process of creating a custom k6 binary. It avoids having to setup a local Go environment, and install xk6 manually.

Note
This tutorial is about creating a custom k6 binary (using Docker). If you want to create a Docker image with a custom k6 binary, refer instead to Using modules with Docker.

Building your first extension

For example, to build a custom k6 binary with the latest versions of k6 and the xk6-kafka and xk6-output-influxdb extensions, run one of the commands below, depending on your operating system:

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.

To build the binary with concrete versions, see the example below (k6 v0.45.1, xk6-kafka v0.19.1, and xk6-output-influxdb v0.4.1):

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 run --rm -e GOOS=windows -v "%cd%:/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

Breaking down the command

The example command line may look a bit intimidating at first, but let’s focus on the first part, which pertains strictly to Docker:

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

This tells Docker to run a new container from an image.

--rm means the container will be destroyed once your build is completed.
-u specifies the user and group IDs of the account on the host machine. This is important for the k6 file to have the same file permissions as the host user.
-v is required to mount the current working directory inside the container, so that the k6 binary can be written to it.

For Windows and Mac, we additionally include the target system as an environment variable:

-e GOOS=<target os>

The remainder is straight from the xk6 documentation, with the exception that we use the grafana/xk6 image rather than a local installation of xk6:

grafana/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]

Caution
The use of --replace should be considered an advanced feature to be avoided unless required.

Referring back to our executed command, note that:

We specify the version as v0.43.1. When you omit the version or specify latest, you build using the latest source code for k6. Consider using a stable release version as a best practice unless you genuinely want the bleeding edge.
We specify a full GitHub URI for the extension repository with each --with. If a version is not specified, the default is again the latest. Check your extension repository for stable release versions, if available, to lock in your version as we’ve done with xk6-kafka@v0.17.0 and xk6-output-influxdb@v0.3.0.
For Windows, we used the --output option to name our result as k6.exe; if not specified, our new binary is k6 within the current directory. If you specify a directory, the new binary will be k6 within that directory. If you specify a path to a non-existent file, e.g. /tmp/k6-extended, this will be the path and filename for the binary.

Run ./k6 version (or k6.exe version) to check that your build is based on the appropriate k6 version and contains the desired extensions. For example:

$ ./k6 version
k6 v0.43.1 ((devel), go1.20.1, darwin/amd64)
Extensions:
  github.com/grafana/xk6-output-influxdb v0.3.0, xk6-influxdb [output]
  github.com/mostafa/xk6-kafka v0.17.0, k6/x/kafka [js]

Running your extended binary

Now that we have our newly built k6 binary, we can run scripts using the functionalities of the bundled extensions.

./k6 run my-script.js

k6.exe run my-script.js

Be sure to specify the binary just built in the current directory as ./k6, or else Linux/Mac could execute another k6 binary on your system path. Windows shells will first search for the binary in the current directory by default.

Encountering issues?

If you’re having issues, search the k6 Community Forum. Someone may have had the same issue in the past.