Set up on Grafana Labs

Install k6

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

Install k6

k6 has packages for Linux, Mac, and Windows. Alternatively, you can use a Docker container or a standalone binary.

You can also use the k6 Studio desktop application to help you generate k6 scripts from a browser recording. Refer to k6 Studio for more details.

Linux

Debian/Ubuntu

curl -fsSL https://dl.k6.io/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/k6-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt-get update
sudo apt-get install k6

Fedora/CentOS

Using dnf (or yum on older versions):

sudo dnf install https://dl.k6.io/rpm/repo.rpm
sudo dnf install k6

MacOS

Using Homebrew:

brew install k6

Windows

If you use the Chocolatey package manager you can install the unofficial k6 package with:

choco install k6

If you use the Windows Package Manager, install the official packages from the k6 manifests (created by the community):

winget install k6 --source winget

Alternatively, you can download and run the latest official installer.

Docker

docker pull grafana/k6

We also have a separate image you can use with chromium installed to run k6 browser tests.

docker pull grafana/k6:master-with-browser

Download the k6 binary

Our GitHub Releases page has a standalone binary for all platforms. After downloading and extracting the archive for your platform, place the k6 or k6.exe binary in your PATH to run k6 from any location.

Using k6 extensions

If you use one or more k6 extensions, you need a k6 binary built with your desired extensions. Head to Explore extension to get started.

Upgrade k6

Upgrade to the latest version of k6 using one of the following commands.

Linux (Debian/Ubuntu)

sudo apt-get update
sudo apt-get install k6

Linux (Fedora/CentOS)

sudo dnf upgrade k6

MacOS

brew upgrade k6

Windows (Chocolatey)

choco upgrade k6

Windows (Windows Package Manager)

winget upgrade k6

Windows (MSI installer)

Download and run the latest official installer.

Docker

Pull the latest image:

docker pull grafana/k6:latest

Binary

Download the latest binary from the GitHub Releases page, and replace your existing installation.

Troubleshooting

If installation fails, check the list of common installation issues. If your problem is not listed and persists, open an issue in the k6 GitHub repository, or report it on our community forum.

k6 Studio

k6 Studio is a desktop application for Windows, macOS, and Linux, that can help you generate k6 scripts from a browser recording, and quickly test your application. You can generate protocol and browser scripts, and test and debug your scripts with a visual interface, without having to touch any code.

For installation instructions, refer to Install k6 Studio.
For more details about k6 Studio, refer to the k6 Studio docs.

Next steps

Now that you have k6 installed in your machine, you can:

Head over to Running k6 to learn how to create and run your first test.
Refer to Configure k6 Intellisense to set up code editing features to your code editor, such as auto-completion of k6 functions.

Configure your code editor

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

Configure your code editor

IntelliSense refers to code editing features like intelligent code completion and quick access to documentation. These features can significantly improve the developer experience and productivity when working on k6 scripts in your editor of choice. Notable features are:

Auto-completion of k6 functions, methods, and classes.
Auto imports of k6 modules.
Access to k6 documentation when writing and hovering code.

Install k6 type definitions

k6 has its TypeScript Type Definition that you can configure with your editor to unlock code editing features.

In Visual Studio Code and IntelliJ IDEA Ultimate, you can configure IntelliSense to recognize the k6 JavaScript API by installing the k6 Types with a package manager.

# create a `package.json` file
$ npm init --yes

# install the k6 types as dev dependency
$ npm install --save-dev @types/k6

Code editor extensions

You can also find k6 code editor extensions for Visual Studio Code and IntelliJ IDEA:

AI assistants (MCP)

Connect k6 authoring and execution tools to MCP-compatible editors or assistants through the k6 MCP server. If you already have k6 installed, you can launch it directly with k6 x mcp — no extra install required.

Configure your AI assistant
Bootstrap your editor with k6 x agent — set up skills and the MCP server in one command for supported editors.

Next steps

Now that you have k6 configured in your code editor, you can:

Head over to Running k6 to learn how to create and run your first test.
Configure your editor for TypeScript support.

Configure your AI assistant

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

Configure your AI assistant

k6 is AI-native. It ships a dedicated toolset that plugs straight into any modern AI editor or agentic workflow, so your assistant can plan, write, validate, and run k6 tests without leaving your codebase.

Two k6 subcommands form the integration:

k6 x agent bootstraps your editor in one command. It installs portable k6 skills (planning, smoke / load / browser tests, Playwright→k6 conversion) and registers the MCP server with Claude Code, Cursor, GitHub Copilot, Codex CLI, OpenCode, or Cline.
k6 x mcp runs the k6 Model Context Protocol server (currently in preview), exposing the tools, prompts, and resources your assistant calls to validate scripts, look up documentation, and execute tests.

If you want the fastest path, jump straight to Bootstrap your editor with k6 x agent. The rest of this page covers running and configuring the MCP server itself.

What your assistant can do for you

Through the k6 MCP server, your AI assistant can:

Write accurate scripts: Create up-to-date scripts by referring to embedded k6 documentation and TypeScript definitions to reduce API hallucinations.
Validate scripts: Catch syntax errors, missing imports, and export default function declarations before execution.
Run tests locally: Execute scripts and review results without leaving your editor.
Generate scripts: Create tests from requirements using guided prompts that follow k6 best practices.
Convert browser tests: Transform Playwright tests into k6 browser scripts while preserving test logic.
Automate provisioning: Discover Terraform resources in your project to automate Grafana Cloud k6 setup.

Quick start with `k6 x agent`

The fastest way to wire everything up is the k6 x agent command, shipped with k6. From your project root:

k6 x agent init claude-code   # or: cursor, vscode-copilot, codex-cli, opencode, cline, --all

k6 x agent init registers the k6 MCP server in your editor’s MCP config and installs portable k6 skills that auto-activate when you ask your assistant to plan, write, or convert tests. See Bootstrap your editor with k6 x agent for the full set of supported editors, bundled skills, and flags.

If your editor isn’t supported by k6 x agent, or you want to author the configuration yourself, see Editors not supported by k6 x agent.

Run the k6 MCP server

The simplest path is to invoke the server through k6 itself. To pin a specific version or run without a k6 install on the host, use the standalone mcp-k6 distribution instead.

k6 subcommand (recommended)

If you already have k6 installed, you also have the k6 MCP server — invoke it as a subcommand:

k6 x mcp

The server is registered as an official subcommand extension. The first time you run k6 x mcp, k6 transparently fetches and runs the extension; subsequent invocations start immediately. By default the server speaks the stdio transport that every MCP client expects.

To also drop in editor skills and auto-register the server in your editor, use k6 x agent init instead of wiring up the server manually.

Verify the command works:

k6 x mcp --help

Note
Auto-extension resolution runs the latest released version. To pin a specific version, use the standalone mcp-k6 distribution below.

Docker

Pull the image:

docker pull grafana/mcp-k6:latest
docker run --rm grafana/mcp-k6 --version

Homebrew (macOS)

Note
If you run mcp-k6 natively, you must also have k6 installed and available in your PATH.

brew tap grafana/grafana
brew install mcp-k6
mcp-k6 --version

Linux packages (deb/rpm)

Install mcp-k6 from the .deb or .rpm packages published on the mcp-k6 GitHub releases.

Open the releases page and select a version.
Download the package that matches your Linux distribution and CPU architecture.

You can check your CPU architecture with:

uname -m

Use the following mapping to pick the right asset:

`uname -m`	Debian/Ubuntu asset	Fedora/RHEL asset
`x86_64`	`amd64` (`.deb`)	`x86_64` (`.rpm`)
`aarch64`	`arm64` (`.deb`)	`aarch64` (`.rpm`)

Debian/Ubuntu (`.deb`)

If you have the GitHub CLI (gh) installed, you can download a specific release asset from the terminal:

MCP_K6_VERSION="vX.Y.Z"

# For amd64/x86_64:
gh release download "$MCP_K6_VERSION" --repo grafana/mcp-k6 --pattern "*linux*amd64*.deb"

# For arm64/aarch64:
# gh release download "$MCP_K6_VERSION" --repo grafana/mcp-k6 --pattern "*linux*arm64*.deb"

sudo apt install ./mcp-k6_*.deb
mcp-k6 --version

If you downloaded the .deb in your browser, run apt from the directory where you saved it:

sudo apt install ./mcp-k6_*.deb
mcp-k6 --version

Fedora/RHEL (`.rpm`)

MCP_K6_VERSION="vX.Y.Z"

# For x86_64:
gh release download "$MCP_K6_VERSION" --repo grafana/mcp-k6 --pattern "*linux*x86_64*.rpm"

# For aarch64:
# gh release download "$MCP_K6_VERSION" --repo grafana/mcp-k6 --pattern "*linux*aarch64*.rpm"

sudo dnf install ./mcp-k6-*.rpm
mcp-k6 --version

If your distro uses yum instead of dnf, run:

sudo yum install ./mcp-k6-*.rpm

Build from source

Clone and install with make:

git clone https://github.com/grafana/mcp-k6
cd mcp-k6
make install

Server flags

The k6 MCP server accepts the following flags, whether you launch it via k6 x mcp or the standalone mcp-k6 binary:

Flag	Default	Description
`--transport`	`stdio`	Transport to use: `stdio` or `http`.
`--addr`	`:8080`	Listen address (HTTP transport only).
`--endpoint`	`/mcp`	HTTP endpoint path (HTTP transport only).
`--stateless`	`false`	Disable session tracking (HTTP transport only).
`--preload`	`false`	Download all embedded documentation bundles at startup.

Run over HTTP

For shared development hosts where multiple clients connect to one server, start the k6 MCP server with the streamable HTTP transport:

k6 x mcp --transport=http --addr=:8080

Clients then connect to http://<host>:8080/mcp.

Caution
The HTTP transport has no built-in authentication. Don’t expose it on a public network — bind it to localhost or a trusted internal interface, and put it behind your own auth proxy if multiple users need access.

Troubleshooting

If your AI assistant cannot connect to the server:

Check the logs: Most editors (like Cursor or VS Code) have an “MCP Output” or “Logs” tab. Check there for “command not found” errors.
Verify k6 is on PATH: If running via k6 x mcp, run which k6 to confirm k6 is globally accessible. If running natively, also run which mcp-k6.
Check k6 version: Auto-extension resolution requires a recent k6 release. Run k6 version and confirm you’re on a version that supports k6 x subcommands.
Docker permissions: Ensure the Docker daemon is running and that your user has permission to execute docker run.
Use MCP Inspector: Use the MCP Inspector to debug the connection independently of your editor.

Configure your editor

Once k6 x mcp runs (or you’ve installed mcp-k6 standalone), wire it up to your editor:

Bootstrap your editor with k6 x agent — one-command setup for Claude Code, Cursor, GitHub Copilot, Codex CLI, OpenCode, and Cline. Manual setup for other MCP clients is documented at the bottom of the same page.

Next steps

Learn about available tools, prompts, and resources: Tools, prompts, and resources

Set up distributed k6

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

Set up distributed k6

It’s possible to run large load tests even when using a single node, or single machine. But, depending on your use case, you might also want to run a distributed Grafana k6 test in your own infrastructure.

A couple of reasons why you might want to do this:

You run your application in Kubernetes and would like k6 to be executed in the same fashion as all your other infrastructure components.
You want to run your tests within your private network for security and/or privacy reasons.

k6 Operator is a Kubernetes operator that you can use to run distributed k6 tests in your cluster.

This section includes the following topics:

Fine-tune OS

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

Fine-tune OS

Note
This page focuses on helping users run large test scripts locally. If you’re just getting started with k6, and haven’t run into a Too Many Open Files error, you can skip these instructions.

When running large test scripts locally, users sometimes run into limits within their OS that prevent them from making the necessary number of requests to complete the test. This limit usually manifests itself in a Too Many Open Files error. These limits, if unchanged, can be a severe bottleneck if you choose to run a bigger or complicated test locally on your machine.

This article shows you how to inspect the OS-imposed limits of your system, tweak them, and scale for larger tests.

Important to note here is that everything that we cover in this article needs to be approached with a healthy dose of caution. As with any changes to your OS, we discourage blindly changing your system settings to a specific value. You should document ways of testing that shows a clear before-and-after relation. E.g. before changing MSL / TIME_WAIT period, confirm that you’re experiencing the issue (error messages, netstat, ss, etc.), change settings conservatively, re-run the test, and note any improvement. This way you can gauge the effect of the optimization, find any negative side-effects, and come up with a range of recommended values.

Before you begin

The following modifications have been tested for Linux, and macOS Sierra 10.12 and above. If you’re using an older macOS version, the process for changing these settings might differ.

Network resource limit

Unix operating system derivatives such as GNU/Linux, BSDs and macOS, can limit the amount of system resources available to a process to safeguard system stability. This includes the total amount of memory, CPU time, or amount of open files a single process is allowed to manage.

Since in Unix everything is a file, including network connections, application testing tools that heavily use the network, such as k6, might reach the configured limit of allowed open files, depending on the amount of network connections used in a particular test.

As mentioned in our opening section, this results in a message like the following being shown during a test:

WARN[0127] Request Failed     error="Get http://example.com/: dial tcp example.com: socket: too many open files"

This message means that the network resource limit has been reached, which will prevent k6 from creating new connections, thus altering the test result. In some cases this may be desired, to measure overall system performance, for example, but in most cases this will be a bottleneck towards testing the HTTP server and web application itself.

The next sections describe ways to increase this resource limit, and allow k6 to run tests with hundreds or thousands of concurrent VUs from a single system.

Viewing limits configuration

Unix systems have two types of resource limits:

Hard limits. The absolute maximum allowed for each user, and can be configured only by the root user.
Soft limits. These can be configured by each user, but cannot be above the hard limit setting.

Linux

On GNU/Linux, you can see the configured limits with the ulimit command.

ulimit -Sa will show all soft limits for the current user:

$ ulimit -Sa
core file size          (blocks, -c) 0
data seg size           (kbytes, -d) unlimited
scheduling priority             (-e) 0
file size               (blocks, -f) unlimited
pending signals                 (-i) 3736
max locked memory       (kbytes, -l) 16384
max memory size         (kbytes, -m) unlimited
open files                      (-n) 1024
pipe size            (512 bytes, -p) 8
POSIX message queues     (bytes, -q) 819200
real-time priority              (-r) 0
stack size              (kbytes, -s) 8192
cpu time               (seconds, -t) unlimited
max user processes              (-u) 3736
virtual memory          (kbytes, -v) unlimited
file locks                      (-x) unlimited

While ulimit -Ha will show all hard limits for the current user:

$ ulimit -Ha
core file size          (blocks, -c) unlimited
data seg size           (kbytes, -d) unlimited
scheduling priority             (-e) 0
file size               (blocks, -f) unlimited
pending signals                 (-i) 3736
max locked memory       (kbytes, -l) 16384
max memory size         (kbytes, -m) unlimited
open files                      (-n) 1048576
pipe size            (512 bytes, -p) 8
POSIX message queues     (bytes, -q) 819200
real-time priority              (-r) 0
stack size              (kbytes, -s) unlimited
cpu time               (seconds, -t) unlimited
max user processes              (-u) 3736
virtual memory          (kbytes, -v) unlimited
file locks                      (-x) unlimited

Note the difference of open files being a maximum of 1024 for the soft limit, while it’s 1048576 for the hard limit.

macOS

In macOS however, you will have a couple of different system imposed limits to take into consideration.

The first one is launchctl limit maxfiles which prints the per-process limits which are specified also as a soft limit and a hard limit. When a soft limit is exceeded a process may receive a signal (for example, if the CPU time or file size is exceeded), but it will be allowed to continue execution until it reaches the hard limit (or modifies its resource limit). kern.maxfiles is the limit of total file descriptors on the entire system - the sum total of all the open files for all processes plus all the files the kernel has open for its own purposes.

sysctl kern.maxfiles

sysctl kern.maxfilesperproc

So, to reiterate, running commands above will show you the system limits on open files and running processes.

Changing limits configuration

The first thing you should consider before changing the configuration is the amount of network connections you expect your test to require. The http_reqs metric in the k6 result summary can hint at this, but a baseline calculation of number of max. VUs * number of HTTP requests in a single VU iteration will deliver a fair approximation. Note that k6 also deals with text files and other resources that count towards the “open files” quota, but network connections are the biggest consumers.

Disabling limits in macOS

Before we can change any system imposed limits in macOS we will need to disable a security feature put in place to prevent us in doing so. You will need to disable System Integrity Protection that was introduced in OS X El Capitan to prevent certain system-owned files and directories from being modified by processes without the proper privileges.

To disable it you will need to restart your Mac and hold down Command + R while it boots. This will boot it into Recovery Mode.

There you should navigate to Utilities which are located in the menu bar at the top of the screen, then open Terminal. Once you have it open, enter the following command:

csrutil disable

Once you press enter and close the Terminal, you can reboot your Mac normally and log into your account.

Changing soft limits

Linux

So, let’s say that we want to run a 1000 VU test which makes 4 HTTP requests per iteration. In this case we could increase the open files limit to 5000, to account for additional non-network file usage. This can be done with the following command:

$ ulimit -n 5000

This changes the limit only for the current shell session.

If we want to persist this change for future sessions, we can add this to a shell startup file. For Bash this would be:

$ echo "ulimit -n 5000" >> ~/.bashrc

macOS

If the soft limit is too low, set the current session to (values written here are usually close to default ones) :

sudo launchctl limit maxfiles 65536 200000

Since sudo is needed, you are prompted for a password.

Changing hard limits

Linux

If the above command results in an error like cannot modify limit: Operation not permitted or value exceeds hard limit, that means that the hard limit is too low, which as mentioned before, can only be changed by the root user.

This can be done by modifying the /etc/security/limits.conf file.

For example, to set both soft and hard limits of the amount of open files per process for the alice account, open /etc/security/limits.conf as root in your text editor of choice and add the following lines:

alice soft nofile 5000
alice hard nofile 1048576

The new limits will be in place after logging out and back in.

Alternatively, * hard nofile 1048576 would apply the setting for all non-root user accounts, and root hard nofile 1048576 for the root user. See the documentation in that file or man bash for the ulimit command documentation.

macOS

Next step will be to configure your new file limits. Open terminal and paste the following command:

sudo nano /Library/LaunchDaemons/limit.maxfiles.plist

This will open a text editor inside your terminal window where you will be prompted to provide your user password and then paste the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
 "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
 <dict>
 <key>Label</key>
 <string>limit.maxfiles</string>
 <key>ProgramArguments</key>
 <array>
 <string>launchctl</string>
 <string>limit</string>
 <string>maxfiles</string>
 <string>64000</string>
 <string>524288</string>
 </array>
 <key>RunAtLoad</key>
 <true/>
 <key>ServiceIPC</key>
 <false/>
 </dict>
</plist>

Pressing Control + X will save the changes and exit the editor. By pasting and saving this we have introduced two different limitations to your maxfiles limit. The first one (64000) is a soft limit, which if reached, will prompt your Mac to prepare to stop allowing new file opens but still let them open. If the second one is reached (524288), a hard limit, you will again start seeing your old friend, the ’too many open files’ error message.

We will use the same procedure to increase the processes limit next.

While in Terminal create a similar file with this command:

sudo nano /Library/LaunchDaemons/limit.maxproc.plist

Again, after prompted for your password, you can paste the following and save and close with Control + X

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple/DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
 <key>Label</key>
 <string>limit.maxproc</string>
 <key>ProgramArguments</key>
 <array>
 <string>launchctl</string>
 <string>limit</string>
 <string>maxproc</string>
 <string>2048</string>
 <string>4096</string>
 </array>
 <key>RunAtLoad</key>
 <true />
 <key>ServiceIPC</key>
 <false />
 </dict>
 </plist>

All that is left after this is to reboot your Mac back to the Recovery Mode, open the Terminal, turn the SIP back on with csrutil enable and check if the limits were changed with commands we used at the beginning.

In most cases these limits should be enough to run most of your simple tests locally for some time, but you can modify the files above to any values you will need in your testing.

Warning
Please be aware that all of these limitations are put in place to protect your operating system from files and applications that are poorly written and might leak memory like in huge quantities. We would suggest not going too overboard with the values, or you might find your system slowing down to a crawl if or when it runs out of RAM.

Local port range

When creating an outgoing network connection the kernel allocates a local (source) port for the connection from a range of available ports.

GNU/Linux

On GNU/Linux you can see this range with:

$ sysctl net.ipv4.ip_local_port_range net.ipv4.ip_local_port_range = 32768 60999

While 28,231 ports might be sufficient for most use cases, this might be a limiting factor if you’re testing with thousands of connections. You can increase it with, for example:

sysctl -w net.ipv4.ip_local_port_range="16384 65000"

Be aware that this range applies to both TCP and UDP, so be conservative with the values you choose and increase as needed.

To make the changes permanent, add net.ipv4.ip_local_port_range=16384 65000 to /etc/sysctl.conf. Last resort tweaks If you still experience network issues with the above changes, consider enabling net.ipv4.tcp_tw_reuse:

sysctl -w net.ipv4.tcp_tw_reuse=1

This will enable a feature to quickly reuse connections in TIME_WAIT state, potentially yielding higher throughput.

macOS/Linux

On macOS the default ephemeral port range is 49152 to 65535, for a total of 16384 ports. You can check this with the sysctl command:

$ sysctl net.inet.ip.portrange.first net.inet.ip.portrange.last

net.inet.ip.portrange.first: 49152
net.inet.ip.portrange.last: 65535

Once you run out of ephemeral ports, you will normally need to wait until the TIME_WAIT state expires (2 * maximum segment lifetime) until you can reuse a particular port number. You can double the number of ports by changing the range to start at 32768, which is the default on Linux and Solaris. (The maximum port number is 65535 so you cannot increase the high end.)

$ sudo sysctl -w net.inet.ip.portrange.first=32768

net.inet.ip.portrange.first: 49152 -> 32768

Note that the official range designated by IANA is 49152 to 65535, and some firewalls may assume that dynamically assigned ports fall within that range. You may need to reconfigure your firewall to use a larger range outside of your local network.

General optimizations

This section goes over some optimizations that are not necessarily dependant on your OS, but may affect your testing.

RAM usage

Depending on the particular k6 test: maximum number of VUs used, number and size of JavaScript dependencies, and complexity of the test script itself, k6 can consume large amounts of system RAM during test execution. While the development is focused on reducing RAM usage as much as possible, a single test run might use tens of gigabytes of RAM under certain scenarios.

As a baseline, count each VU instance to require between 1MB and 5MB of RAM, depending on your script complexity and dependencies. This is roughly between 1GB and 5GB of required system RAM for a 1,000 VU test, so make sure that sufficient physical RAM is available to meet your test demands.

If you need to decrease the RAM usage, you could use the option --compatibility-mode=base. Read more on JavaScript Compatibility Mode.

Virtual memory

In addition to physical RAM, ensure that the system is configured with an appropriate amount of virtual memory, or swap space, in case higher memory usage bursts are required.

You can see the status and amount of available swap space on your system with the commands swapon or free.

We won’t go into swap configuration details here, but you can find several guides online.

Network performance

Because k6 can generate and sustain large amounts of network traffic, it also stresses the network stack of modern operating systems. Under certain loads or network conditions it’s possible to achieve higher throughput and better performance by tweaking some network settings of the operating system or restructuring the network conditions of the test.

TCP TIME_WAIT period

TCP network applications, such as web clients and servers, are assigned a network socket pair (a unique combination of local address, local port, remote address, and remote port) for each incoming or outgoing connection. Typically this socket pair is used for a single HTTP request/response session, and closed soon after. However, even after a connection is successfully closed by the application, the kernel might still reserve resources for quickly reopening the same socket if a new matching TCP segment arrives. This also occurs during network congestion where some packets get lost in transmission. This places the socket in a TIME_WAIT state, and is released once the TIME_WAIT period expires. This period is typically configured between 15 seconds and 2 minutes.

The problem some applications like k6 might run into is causing a high number of connections to end up in the TIME_WAIT state, which can prevent new network connections being created.

In these scenarios, before making changes to the system network configuration, which might have adverse side-effects for other applications, it’s preferable to first take some common testing precautions. Use different server ports or IPs

Since sockets are uniquely created for a combination of local address, local port, remote address and remote port, a safe workaround for avoiding TIME_WAIT congestion is using different server ports or IP addresses.

For example, you can configure your application to run on ports :8080, :8081, :8082, etc. and spread out your HTTP requests across these endpoints.

Usage collection

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

Usage collection

By default, k6 sends an anonymous usage report each time it is run, so that we can track relevant information to be able to build the product making better data-driven decisions. Prioritizing the features that benefit the most and reducing the impact of changes.

The report can be turned off by setting the no usage report option setting the environment variable K6_NO_USAGE_REPORT or by adding the flag --no-usage-report when executing k6.

The usage report does not contain any information about what you are testing. The contents are the following:

An anonymous installation ID (installation_id), described below.
The k6 version (string, e.g. “0.17.2”)
Max VUs configured (number)
Test duration (number)
Total stages duration (number)
VU iterations configured (number)
The running program’s operating system target (darwin, freebsd, linux…)
The running program’s architecture target (386, amd64, arm, s390x…)
The list of JavaScript imported modules (k6/http, k6/experimental/webcrypto, …)
The list of used outputs (json, influxdb, …)
The list of used extensions, each with its Go module path, version, and type (js, output, or subcommand)
The test run ID if the test was executed in the cloud or was outputed to it
The number of parsed files and how many were TypeScript files.
The number of times require was called.
The build origin of k6 (release, xk6, provisioning, …)
Whether global was accessed.

Note
The module and output lists contain only k6 built-in names. An extension is reported only if it’s listed in the public k6 extension catalog. Private and unlisted extensions are never reported.

Running an extension subcommand (k6 x <name>) also sends a usage report. It contains the anonymous installation ID, the k6 version, the operating system and architecture targets, whether k6 runs in a CI system, the build origin, and the invoked extension’s entry as described above. The K6_NO_USAGE_REPORT environment variable and the noUsageReport configuration file option turn this report off too. The --no-usage-report flag has no effect here, because k6 x passes all flags unchanged to the extension.

Anonymous installation ID

Starting with k6 v2.3.0, usage reports include a random UUID to help estimate the number of active k6 installations over time. Reusing the ID lets Grafana distinguish repeated runs from the same installation from runs across many installations, which helps guide k6 development. The ID is randomly generated, not derived from a username, hostname, or machine fingerprint.

k6 saves the ID in an installation-id file and reuses it between runs:

Operating system	File location
Linux and other Unix systems	`$XDG_CONFIG_HOME/k6/installation-id`, or `$HOME/.config/k6/installation-id` if `XDG_CONFIG_HOME` is unset or empty.
macOS	`$HOME/Library/Application Support/k6/installation-id`
Windows	`%AppData%/k6/installation-id`

Setting a custom configuration file with --config does not change this location. If you delete the ID file, k6 creates a new ID the next time it sends a usage report. This resets the local identifier; it does not disable reporting or delete reports already sent. If k6 cannot read or save the ID, it sends the report without the ID.

When you disable usage reporting, k6 does not read or create the ID file and sends no report. For example:

k6 run --no-usage-report script.js

For extension subcommands, set K6_NO_USAGE_REPORT=true instead of passing --no-usage-report.

This report is sent to an HTTPS server that collects statistics on k6 usage.

k6 is an open-source project and for those interested, the actual code that generates and sends the usage report can be directly reviewed here.

Set up on Grafana Labs

Install k6

Install k6

Linux

Debian/Ubuntu

Fedora/CentOS

MacOS

Windows

Docker

Download the k6 binary

Using k6 extensions

Upgrade k6

Linux (Debian/Ubuntu)

Linux (Fedora/CentOS)

MacOS

Windows (Chocolatey)

Windows (Windows Package Manager)

Windows (MSI installer)

Docker

Binary

Troubleshooting

k6 Studio

Next steps

Configure your code editor

Configure your code editor

Install k6 type definitions

Code editor extensions

AI assistants (MCP)

Next steps

Configure your AI assistant

Configure your AI assistant

What your assistant can do for you

Quick start with k6 x agent

Run the k6 MCP server

k6 subcommand (recommended)

Docker

Homebrew (macOS)

Linux packages (deb/rpm)

Debian/Ubuntu (.deb)

Fedora/RHEL (.rpm)

Build from source

Server flags

Run over HTTP

Troubleshooting

Configure your editor

Next steps

Set up distributed k6

Set up distributed k6

Fine-tune OS

Fine-tune OS

Before you begin

Network resource limit

Viewing limits configuration

Linux

macOS

Changing limits configuration

Disabling limits in macOS

Changing soft limits

Linux

macOS

Changing hard limits

Linux

macOS

Local port range

GNU/Linux

macOS/Linux

General optimizations

RAM usage

Virtual memory

Network performance

TCP TIME_WAIT period

Read more

Usage collection

Usage collection

Anonymous installation ID

Quick start with `k6 x agent`

Debian/Ubuntu (`.deb`)

Fedora/RHEL (`.rpm`)