k6 run

Run a load test script with k6

k6 run

Run a load test script. This is the primary command for executing k6 tests.

Synopsis

k6 run [flags] <script>

Description

The k6 run command starts a test and exposes a REST API to interact with it. The command loads a test script, initializes virtual users (VUs), and executes the test according to the configured options.

The script argument can be:

• A path to a JavaScript test file
• A path to a k6 archive (.tar file)
• - to read the script from stdin

Examples

# Run a single VU, once
k6 run script.js

# Run a single VU, 10 times
k6 run -i 10 script.js

# Run 5 VUs, splitting 10 iterations between them
k6 run -u 5 -i 10 script.js

# Run 5 VUs for 10 seconds
k6 run -u 5 -d 10s script.js

# Ramp VUs from 0 to 100 over 10s, stay there for 60s, then 10s down to 0
k6 run -u 0 -s 10s:100 -s 60s:100 -s 10s:0

# Send metrics to a remote storage using the OpenTelemetry output
k6 run -o opentelemetry script.js

Flags

Test Execution

-u, --vus · int · default: "1"

Number of virtual users to run concurrently

-d, --duration · duration

Test duration limit (e.g., 10s, 5m, 1h30m)

-i, --iterations · int

Script total iteration limit (among all VUs)

-s, --stage · string[]

Add a stage in the format [duration]:[target] (e.g., 10s:100). Can be specified multiple times.

-p, --paused · boolean

Start the test in a paused state

--execution-segment · string

Limit execution to a specified segment (e.g., 10%, 1/3, 0.2:2/3)

--execution-segment-sequence · string

The execution segment sequence for distributed execution

Test Lifecycle

--no-setup · boolean

Skip running the setup() function

--no-teardown · boolean

Skip running the teardown() function

-l, --linger · boolean

Keep the API server alive past test end

HTTP Options

--max-redirects · int · default: "10"

Follow at most n redirects

--batch · int · default: "20"

Maximum parallel batch requests

--batch-per-host · int · default: "6"

Maximum parallel batch requests per host

--rps · int

Limit requests per second (0 = unlimited)

--user-agent · string

User agent string for HTTP requests

--http-debug · string

Log all HTTP requests and responses. Use --http-debug=full to include body.

--insecure-skip-tls-verify · boolean

Skip verification of TLS certificates

--no-connection-reuse · boolean

Disable keep-alive connections

--no-vu-connection-reuse · boolean

Don’t reuse connections between iterations

--min-iteration-duration · duration

Minimum amount of time k6 will take executing a single iteration

-w, --throw · boolean

Throw warnings (like failed HTTP requests) as errors

--discard-response-bodies · boolean

Read but don’t process or save HTTP response bodies

Network Configuration

--blacklist-ip · string[]

Blacklist an IP range from being called

--block-hostnames · string[]

Block a case-insensitive hostname pattern (with optional leading wildcard)

--local-ips · string

Client IP ranges and/or CIDRs from which each VU will make requests

--dns · string

DNS resolver configuration. Format: ttl=VALUE,select=VALUE,policy=VALUE

Runtime Options

-e, --env · string[]

Add/override environment variable with VAR=value

--include-system-env-vars · boolean

Pass the real system environment variables to the runtime

--compatibility-mode · string · default: "extended"

JavaScript compatibility mode: extended or base

-t, --type · string

Override test type: js or archive

Output and Metrics

-o, --out · string[]

URI for an external metrics database (can be specified multiple times)

--summary-mode · string · default: "compact"

Summary display mode: compact, full, or disabled

--summary-export · string

Output the end-of-test summary report to a JSON file

--summary-trend-stats · string[]

Define stats for trend metrics (e.g., avg,p(95),p(99))

--summary-time-unit · string

Time unit for displaying trend stats: s, ms, or us

--system-tags · string[]

Only include these system tags in metrics

--tag · string[]

Add a tag to be applied to all samples in the format [name]=[value]

--no-thresholds · boolean

Don’t run thresholds

--console-output · string

Redirect console logging to the provided output file

Other Options

--config · string

Path to config file (default: ./k6.json)

--no-usage-report · boolean

Don’t send anonymous usage statistics

--traces-output · string · default: "none"

Output for k6 traces: none or otel[=host:port]

Exit Codes

k6 uses specific exit codes to indicate different error conditions:

• 0 - Test passed successfully
• 99 - Test failed due to threshold violations
• 108 - Test marked as failed via exec.test.status
• Other non-zero codes indicate various errors

REST API

When running a test, k6 exposes a REST API (by default on localhost:6565) that can be used to:

• Get test status
• Pause/resume execution
• Scale VUs dynamically
• Retrieve metrics

Use the global --address flag to configure the API server address.

See Also

• k6 archive - Create an archive of your test
• k6 cloud - Run tests in Grafana Cloud
• CLI options reference