Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 36 ยท Getting Started

Installing k6 and Running Your First Test

Install k6 on Windows, macOS, Linux or Docker, write a first script, run it with k6 run, override options on the command line, and learn what the output means.

Getting k6 onto your machine takes a minute: it is one self-contained binary with no runtime to install. This lesson shows the common ways to install it, how to run a script, and how to change the load from the command line without editing the file. You will also build a tiny stand-in for the "request, time it, report" loop that sits at the heart of every k6 run.

Installing k6

Pick the option that matches your system. All of them give you the same k6 command.

System Command
Windows (winget) winget install k6 --source winget
Windows (Chocolatey) choco install k6
macOS (Homebrew) brew install k6
Debian/Ubuntu add the Grafana k6 apt repository, then sudo apt-get install k6
Docker docker run --rm -i grafana/k6 run - <script.js
Any system download the binary from the project's GitHub releases page and put it on your PATH

Check the install:

Terminal
k6 version

It prints the version, the Go version it was built with and your platform. The package-manager commands change over time, so if one fails, follow the install page of the official k6 documentation.

The Docker form reads the script from standard input (-). If the script imports other files or reads data files, mount your folder instead: docker run --rm -i -v "$PWD":/work -w /work grafana/k6 run script.js.

Writing and running a script

Save this as first.js:

JavaScript
import http from 'k6/http';
import { sleep } from 'k6';

export const options = {
  vus: 5,
  duration: '10s',
};

export default function () {
  const res = http.get('http://localhost:3000/health');
  console.log(`status ${res.status} in ${res.timings.duration} ms`);
  sleep(1);
}

Run it with:

Terminal
k6 run first.js

k6 prints a banner with the script name and the planned load, then a live progress bar (virtual users, iterations, elapsed time) while the test runs, and finally the end-of-test summary. The summary is the subject of the lesson Reading the End-of-Test Summary; for now just notice that it lists every metric k6 collected, with http_req_duration being the one most people look at first.

console.log output appears between the progress updates. It is handy while developing, but printing on every iteration in a big test slows things down and floods the terminal, so remove it before real runs.

Overriding options from the command line

Flags beat the options object, which makes quick experiments easy without editing the file:

Terminal
k6 run --vus 20 --duration 30s first.js
k6 run --iterations 100 --vus 10 first.js
k6 run --quiet first.js

The order of precedence, from strongest to weakest, is: command-line flags, environment variables, the options object in the script, and k6's defaults (one VU, one iteration). Knowing that order saves you from the confusion of "why is my duration ignored?"; usually a flag or an environment variable wins.

Other flags worth knowing right now:

  • --out json=results.json writes every data point to a file (see Output formats).
  • --http-debug prints raw requests and responses, useful when a call fails mysteriously.
  • k6 run -e BASE_URL=http://localhost:3000 first.js passes an environment variable to the script, read as __ENV.BASE_URL.
  • k6 inspect first.js prints the resolved options without running anything.

What a k6 run does

sequenceDiagram
  participant You
  participant k6
  participant Server
  You->>k6: k6 run first.js
  k6->>k6: load script, resolve options
  k6->>k6: init code runs once per VU
  loop every VU, until duration ends
    k6->>Server: HTTP request
    Server-->>k6: response
    k6->>k6: record timings, run sleep
  end
  k6-->>You: end-of-test summary, exit code

One process, many VUs, one summary at the end.

The exit code matters: 0 means the test ran and every threshold passed; a non-zero code (99 for failed thresholds) tells a CI system the build should fail. You will use this in thresholds.

A stand-in for the request loop

This is not k6; it is plain Node.js that does what the script above does: a few VUs call an endpoint for a fixed number of rounds, each request is timed, and a short report is printed. The server and counts are deterministic; the timing is not, so the program only prints what is always true.

Node.js Stand-in: time requests like http_req_duration

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The same idea scales up in real k6: the engine records one data point per request, and everything in the summary (average, median, percentiles) is computed from those points.

When something goes wrong

A few early stumbles and what they mean:

  • command not found: k6: the install directory is not on your PATH, or you need to open a new terminal.
  • connection refused in the summary or logs: nothing is listening at the URL. Start your app first.
  • GoError: ... or ReferenceError: ... is not defined: remember the script runs in k6's runtime, not Node. require and process do not exist.
  • Script runs once and stops: you set no vus/duration, so k6 used its default of one VU and one iteration.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command runs a script with 20 virtual users for 30 seconds without editing it?

    k6 run accepts --vus and --duration, and these flags override the options object in the script.
  2. 2. If a script has no vus or duration and no flags are passed, what does k6 do?

    The defaults are one VU and one iteration, which is great for debugging a script.
  3. 3. Which has the highest precedence when the same option is set in several places?

    CLI flags override environment variables, which override the options object, which overrides the defaults.
  4. 4. Why should you remove console.log calls from big runs?

    Logging in every iteration of a large test produces enormous output and slows the run.

Summary

  • k6 is one binary; install it with a package manager, Docker or a release download, and check it with k6 version.
  • k6 run script.js runs a test and prints a live progress bar and an end-of-test summary.
  • CLI flags (--vus, --duration, --iterations) override environment variables and the options object.
  • A non-zero exit code means thresholds failed, which is how CI notices.
  • With no options, k6 runs one iteration with one VU, ideal for debugging a script.

Next: Types of Load Tests