Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us