Skip to main content
Options configure how your k6 test runs. They control aspects like virtual users, duration, thresholds, tags, and many other test behaviors.

​
What are options?

Options determine test execution parameters such as:
  • Number of virtual users (VUs)
  • Test duration or iterations
  • Thresholds for pass/fail criteria
  • Tags for organizing metrics
  • Scenarios for complex workload patterns
  • Network settings and timeouts
Options provide the configuration layer that controls your test execution, separate from the test logic itself.

​
Where to set options

k6 provides multiple places to define options, each suited for different use cases:
Set options in your test script using the options object. This is the recommended approach for most cases.
import http from 'k6/http';

export const options = {
  vus: 10,
  duration: '30s',
  thresholds: {
    http_req_duration: ['p(95)<200'],
  },
};

export default function () {
  http.get('http://test.k6.io/');
}
Benefits:
  • Version controlled with your test
  • Easy to reuse and share
  • Self-documenting

​
Order of precedence

When options are set in multiple places, k6 uses this precedence order (highest to lowest):
1

CLI flags (highest)

Command-line flags override everything else
2

Environment variables

K6_ prefixed environment variables
3

Script options

Options exported in the test script
4

Config file

Options from —config file
5

Defaults (lowest)

k6’s built-in default values
CLI flags have the highest precedence. They override all other option sources.

​
Common options

Here are the most frequently used options:

​
Virtual users and duration

export const options = {
  vus: 10,           // Number of virtual users
  duration: '30s',   // How long to run
};

​
Thresholds

Define pass/fail criteria: 
export const options = {
  thresholds: {
    http_req_failed: ['rate<0.01'],    // Less than 1% errors
    http_req_duration: ['p(95)<200'],  // 95% under 200ms
    checks: ['rate>0.9'],              // 90% of checks pass
  },
};

​
Tags

Add tags to all metrics: 
export const options = {
  tags: {
    environment: 'staging',
    team: 'backend',
  },
};

​
Scenarios

Define complex workload patterns: 
export const options = {
  scenarios: {
    load_test: {
      executor: 'ramping-vus',
      startVUs: 0,
      stages: [
        { duration: '1m', target: 50 },
        { duration: '3m', target: 50 },
        { duration: '1m', target: 0 },
      ],
    },
  },
};

​
Complete example

Here’s a comprehensive example showing various options: 
import http from 'k6/http';
import { sleep } from 'k6';

export const options = {
  // Load pattern
  stages: [
    { duration: '30s', target: 10 },
    { duration: '1m', target: 10 },
    { duration: '30s', target: 0 },
  ],
  
  // Pass/fail criteria
  thresholds: {
    http_req_failed: ['rate<0.01'],
    http_req_duration: ['p(95)<500', 'p(99)<1000'],
    checks: ['rate>0.95'],
  },
  
  // Tags for all metrics
  tags: {
    test_type: 'load',
    environment: 'production',
  },
  
  // Network settings
  noConnectionReuse: false,
  userAgent: 'MyK6LoadTest/1.0',
  
  // Limits
  maxRedirects: 10,
};

const baseUrl = __ENV.BASE_URL || 'https://test.k6.io';

export default function () {
  http.get(baseUrl);
  sleep(1);
}

​
Using environment variables in options

Reference environment variables in your script options: 
import http from 'k6/http';

export const options = {
  vus: __ENV.VUS || 10,
  duration: __ENV.DURATION || '30s',
  thresholds: {
    http_req_duration: [`p(95)<${__ENV.P95_THRESHOLD || 200}`],
  },
};

export default function () {
  http.get(__ENV.BASE_URL || 'https://test.k6.io');
}
Run with custom values: 
k6 run --env VUS=20 --env DURATION=1m --env BASE_URL=https://example.com script.js

​
Accessing options at runtime

Access the resolved option values during test execution: 
import exec from 'k6/execution';

export const options = {
  stages: [
    { duration: '5s', target: 100 },
    { duration: '5s', target: 50 },
  ],
};

export default function () {
  // Access the first stage's target
  const firstStageTarget = exec.test.options.scenarios.default.stages[0].target;
  console.log(`First stage target: ${firstStageTarget}`); // 100
}

​
Override examples

# Script has duration: '30s'
k6 run --duration 1m script.js
# Runs for 1 minute instead

​
Using config files

Create a reusable config file:
options.json
{
  "vus": 10,
  "duration": "30s",
  "thresholds": {
    "http_req_failed": ["rate<0.01"],
    "http_req_duration": ["p(95)<200"]
  },
  "tags": {
    "environment": "staging"
  }
}
Use it with your test: 
k6 run --config options.json script.js
Or load it in your script: 
const testConfig = JSON.parse(open('./config/test.json'));
export const options = testConfig;

​
Best practices

Use script options

Keep options in your script for version control and easy reuse.

CLI for overrides

Use CLI flags to quickly test variations without editing the script.

Environment variables for CI/CD

Use env vars to configure tests differently across environments.

Document your options

Add comments explaining why you chose specific option values.

​
Next steps

Options Reference

See the complete list of all available options with detailed descriptions

Build docs developers (and LLMs) love

Get started for freeTalk to us