Installation

Overview

k6 is available for all major platforms. Choose your preferred installation method below.

Linux

Install via package managers or download binaries

macOS

Install with Homebrew or download directly

Windows

Install with package managers or executables

Docker

Run k6 in containers without installation

Installation methods

macOS
Linux
Windows
Docker

Using Homebrew

The easiest way to install k6 on macOS is using Homebrew:

brew install k6

Verify installation

Check that k6 is installed correctly:

k6 version

Homebrew automatically handles updates. Run brew upgrade k6 to get the latest version.

Debian/Ubuntu

Install k6 using the apt package manager:

sudo gpg -k
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
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/RedHat

Install using the yum package manager:

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

Verify installation

k6 version

For other Linux distributions, you can download pre-compiled binaries from the GitHub releases page.

Using Chocolatey

If you have Chocolatey installed:

choco install k6

Using Windows Package Manager

If you have winget installed:

winget install k6 --source winget

Manual installation

Download the installer

Download the latest .msi installer from the k6 releases page.

Run the installer

Double-click the downloaded .msi file and follow the installation wizard.

Verify installation

Open Command Prompt or PowerShell and run:

k6 version

Using Docker

Run k6 directly from a Docker container without installing:

docker pull grafana/k6:latest

Run a test

To run a test script with Docker:

docker run --rm -v $(pwd):/scripts grafana/k6:latest run /scripts/test.js

Docker Compose

For more complex setups, use Docker Compose. Create a docker-compose.yml file:

version: '3.8'
services:
  k6:
    image: grafana/k6:latest
    volumes:
      - ./scripts:/scripts
    command: run /scripts/test.js

Then run:

docker-compose up

Docker is perfect for CI/CD environments where you want consistent, reproducible test execution.

Build from source

For developers who want to build k6 from source:

Install Go

Make sure you have Go installed (version 1.21 or later).

go version

Clone the repository

Clone the k6 repository from GitHub:

git clone https://github.com/grafana/k6.git
cd k6

Build k6

Build the k6 binary:

go build -o k6 .

Verify the build

Check that k6 was built successfully:

./k6 version

Building from source gives you access to the latest features and allows you to customize k6 for your specific needs.

Install k6 extensions

k6 has a rich ecosystem of extensions that add support for new protocols and features:

Using xk6

xk6 is the official tool for building k6 with extensions:

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

# Build k6 with extensions
xk6 build --with github.com/grafana/xk6-sql

Explore available extensions at the k6 extensions page.

Verify your installation

After installation, verify k6 is working correctly:

k6 version

Troubleshooting

k6 command not found

If you get a “command not found” error:

Make sure k6 is in your PATH
Try closing and reopening your terminal
On Windows, restart Command Prompt or PowerShell after installation

Permission denied on Linux/macOS

If you encounter permission errors:

sudo chmod +x /usr/local/bin/k6

Or use sudo when running installation commands.

Docker volume mounting issues

If your test scripts aren’t being found in Docker:

Make sure you’re using absolute paths or $(pwd)
On Windows, use ${PWD} in PowerShell or %cd% in Command Prompt
Check that the script file exists in the mounted directory

Next steps

Quick start guide

Now that k6 is installed, let’s run your first load test!

Always verify your k6 installation before running production tests. Use k6 version to ensure you’re running the expected version.

Getting Started

Core Concepts

Writing Tests

Test Types

Protocol Support

Results & Visualization

Extensions

Installation

Overview

Linux

macOS

Windows

Docker

Installation methods

Using Homebrew

Verify installation

Debian/Ubuntu

Fedora/CentOS/RedHat

Verify installation

Using Chocolatey

Using Windows Package Manager

Manual installation

Using Docker

Run a test

Docker Compose

Build from source

Install k6 extensions

Using xk6

Verify your installation

Troubleshooting

Next steps

Quick start guide

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Writing Tests

Test Types

Protocol Support

Results & Visualization

Extensions

​Overview

Linux

macOS

Windows

Docker

​Installation methods

​Using Homebrew

​Verify installation

​Debian/Ubuntu

​Fedora/CentOS/RedHat

​Verify installation

​Using Chocolatey

​Using Windows Package Manager

​Manual installation

​Using Docker

​Run a test

​Docker Compose

​Build from source

​Install k6 extensions

​Using xk6

​Verify your installation

​Troubleshooting

​Next steps

Quick start guide

Build docs developers (and LLMs) love

Overview

Installation methods

Using Homebrew

Verify installation

Debian/Ubuntu

Fedora/CentOS/RedHat

Verify installation

Using Chocolatey

Using Windows Package Manager

Manual installation

Using Docker

Run a test

Docker Compose

Build from source

Install k6 extensions

Using xk6

Verify your installation

Troubleshooting

Next steps