Installing K6 on Mac, Windows, and Linux

K6 is a single binary — there is no JVM to install, no virtual environment to activate, no package.json to initialise. Installation takes under two minutes on any platform. This lesson walks through every supported method and gets you to a verified working install.

Installation by platform

macOS (recommended: Homebrew)

brew install k6

If you do not have Homebrew, install it first from brew.sh — it is the standard macOS package manager and worth having regardless.

Windows (recommended: winget)

winget install k6 --source winget

Alternatively, download the Windows installer directly from the K6 releases page on GitHub — the .msi file handles PATH setup automatically.

Linux (Ubuntu/Debian)

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

For RPM-based distributions (Fedora, CentOS, RHEL), the K6 documentation at k6.io/docs/get-started/installation/ provides the equivalent yum or dnf commands.

Docker (no local install required)

docker run --rm -i grafana/k6 run - <script.js

The - tells K6 to read the script from stdin. Pipe your local file in with <script.js. This is useful in CI environments where installing binaries is restricted, or for quick one-off runs without touching your system PATH.

Verify your installation

After any of the above, confirm K6 is on your PATH:

k6 version

You should see output like:

k6 v0.54.0 (go1.22.4, linux/amd64)

The exact version number will differ. If the command is not found, the most common cause is a PATH issue — confirm the install location (usually /usr/local/bin on macOS/Linux) is included in your shell's PATH.

The installation and first-run flow

IDE setup

VS Code is the recommended editor for K6 scripts. Install the K6 extension from the marketplace — it provides syntax highlighting for K6 scripts, IntelliSense autocomplete for K6 modules, and the ability to run K6 directly from the editor via the command palette.

For type safety, the @types/k6 TypeScript definitions work with VS Code's TypeScript server even though K6 does not use Node.js at runtime:

npm install --save-dev @types/k6

This gives you autocomplete and inline documentation in your editor. The types do not affect how K6 executes the script — they are a developer-experience layer only.

A note on K6's JavaScript runtime

K6 ships Goja — a JavaScript engine written in Go. It implements ES2015+ (arrow functions, destructuring, template literals, const/let, import/export) but it is not Node.js. This means:

• require() (CommonJS) does not work — use ES module import syntax.
• Browser globals (window, document, localStorage) do not exist.
• Node.js built-ins (fs, path, http) are not available.
• npm packages that depend on Node.js or browser APIs will not run inside K6.

K6 scripts use import exclusively, and all imports must be either K6's built-in modules or local JavaScript files you have written yourself.

// ✅ Valid K6 imports
import http from 'k6/http';
import { check, sleep } from 'k6';
import { SharedArray } from 'k6/data';
 
// ❌ These will throw at runtime
import axios from 'axios';
import fs from 'fs';

⚠️ Common mistakes

• Running npm install k6. There is no npm package that installs the K6 CLI. K6 is a binary installed via Homebrew, winget, apt, or Docker — not via npm. npm is only used to install TypeScript type definitions for editor support.
• Trying to require() npm packages inside a K6 script. K6's runtime is not Node.js. require('axios') will throw at startup. Use K6's built-in http module for all HTTP requests.
• Forgetting to verify PATH after install on Linux. The binary lands in /usr/bin/k6 when installed via the official repository. If k6 version fails immediately after install, run which k6 and confirm the path is in your $PATH.

🎯 Practice task

Install K6 and confirm it works. Under 10 minutes.

1. Follow the installation steps for your platform above.
2. Run k6 version and confirm the version prints without error.
3. Create a file called smoke.js with this content and run it:

import http from 'k6/http';
import { check } from 'k6';
 
export default function () {
  const res = http.get('https://test.k6.io');
  check(res, { 'status 200': (r) => r.status === 200 });
}

k6 run smoke.js

You should see K6 output including HTTP metrics and a summary table. A green ✓ next to your check means the assertion passed.

4. Install the VS Code K6 extension if you use VS Code. Open smoke.js and confirm you get autocomplete on http..

You are now ready to write your first real K6 script. The next lesson builds one from scratch, explaining every line.