> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/grafana/k6/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration File

> k6 JSON configuration file format

# Configuration File

k6 supports configuration via a JSON file, allowing you to define test options without cluttering your test scripts.

## Overview

By default, k6 looks for a configuration file named `k6.json` in the current directory. You can specify a different file using the `--config` flag or `K6_CONFIG` environment variable.

```bash theme={null}
# Use default k6.json
k6 run script.js

# Use custom config file
k6 run --config /path/to/config.json script.js

# Via environment variable
K6_CONFIG=/path/to/config.json k6 run script.js
```

## Configuration Precedence

Configuration is loaded in this order (later overrides earlier):

1. **Default values** - Built-in k6 defaults
2. **Configuration file** - `k6.json` or specified via `--config`
3. **Script options** - `export const options = {}` in your script
4. **Environment variables** - `K6_*` environment variables
5. **CLI flags** - Command-line arguments (highest priority)

## File Format

The configuration file is JSON with the following structure:

```json theme={null}
{
  "vus": 10,
  "duration": "30s",
  "iterations": 1000,
  "stages": [
    { "duration": "10s", "target": 50 },
    { "duration": "30s", "target": 50 },
    { "duration": "10s", "target": 0 }
  ],
  "thresholds": {
    "http_req_duration": ["p(95)<500"],
    "http_req_failed": ["rate<0.01"]
  },
  "out": ["json=results.json"],
  "linger": false,
  "noUsageReport": true
}
```

## Configuration Options

### Execution Options

<ParamField path="vus" type="int" default="1">
  Number of virtual users.

  ```json theme={null}
  {"vus": 10}
  ```
</ParamField>

<ParamField path="duration" type="string">
  Test duration (e.g., `30s`, `5m`, `1h`).

  ```json theme={null}
  {"duration": "5m"}
  ```
</ParamField>

<ParamField path="iterations" type="int">
  Total iteration limit across all VUs.

  ```json theme={null}
  {"iterations": 1000}
  ```
</ParamField>

<ParamField path="stages" type="array">
  Ramping configuration stages.

  ```json theme={null}
  {
    "stages": [
      {"duration": "10s", "target": 100},
      {"duration": "30s", "target": 100},
      {"duration": "10s", "target": 0}
    ]
  }
  ```
</ParamField>

<ParamField path="scenarios" type="object">
  Advanced scenario configuration.

  ```json theme={null}
  {
    "scenarios": {
      "constant_load": {
        "executor": "constant-vus",
        "vus": 50,
        "duration": "5m"
      },
      "ramping_load": {
        "executor": "ramping-vus",
        "startVUs": 0,
        "stages": [
          {"duration": "2m", "target": 100}
        ]
      }
    }
  }
  ```
</ParamField>

### HTTP Options

<ParamField path="batch" type="int" default="20">
  Maximum parallel batch requests.

  ```json theme={null}
  {"batch": 50}
  ```
</ParamField>

<ParamField path="batchPerHost" type="int" default="6">
  Maximum parallel batch requests per host.

  ```json theme={null}
  {"batchPerHost": 10}
  ```
</ParamField>

<ParamField path="maxRedirects" type="int" default="10">
  Maximum HTTP redirects to follow.

  ```json theme={null}
  {"maxRedirects": 5}
  ```
</ParamField>

<ParamField path="userAgent" type="string">
  User-Agent string for requests.

  ```json theme={null}
  {"userAgent": "MyLoadTest/1.0"}
  ```
</ParamField>

<ParamField path="insecureSkipTLSVerify" type="boolean">
  Skip TLS certificate verification.

  ```json theme={null}
  {"insecureSkipTLSVerify": true}
  ```
</ParamField>

<ParamField path="noConnectionReuse" type="boolean">
  Disable HTTP keep-alive.

  ```json theme={null}
  {"noConnectionReuse": true}
  ```
</ParamField>

<ParamField path="noVUConnectionReuse" type="boolean">
  Don't reuse connections between iterations.

  ```json theme={null}
  {"noVUConnectionReuse": true}
  ```
</ParamField>

<ParamField path="discardResponseBodies" type="boolean">
  Don't save HTTP response bodies.

  ```json theme={null}
  {"discardResponseBodies": true}
  ```
</ParamField>

### Thresholds

<ParamField path="thresholds" type="object">
  Pass/fail criteria for metrics.

  ```json theme={null}
  {
    "thresholds": {
      "http_req_duration": [
        "p(95)<500",
        "p(99)<1000"
      ],
      "http_req_failed": ["rate<0.01"],
      "checks": ["rate>0.95"]
    }
  }
  ```
</ParamField>

### Output Configuration

<ParamField path="out" type="array">
  Metrics output destinations.

  ```json theme={null}
  {
    "out": [
      "json=results.json",
      "influxdb=http://localhost:8086/k6",
      "cloud"
    ]
  }
  ```
</ParamField>

<ParamField path="summaryTrendStats" type="array">
  Statistics to calculate for trends.

  ```json theme={null}
  {
    "summaryTrendStats": ["avg", "min", "med", "max", "p(90)", "p(95)", "p(99)"]
  }
  ```
</ParamField>

<ParamField path="summaryTimeUnit" type="string">
  Time unit for trend stats: `s`, `ms`, `us`.

  ```json theme={null}
  {"summaryTimeUnit": "ms"}
  ```
</ParamField>

<ParamField path="systemTags" type="array">
  System tags to include in metrics.

  ```json theme={null}
  {
    "systemTags": ["proto", "status", "method", "url"]
  }
  ```
</ParamField>

### Test Behavior

<ParamField path="paused" type="boolean">
  Start test in paused state.

  ```json theme={null}
  {"paused": true}
  ```
</ParamField>

<ParamField path="noSetup" type="boolean">
  Skip `setup()` function.

  ```json theme={null}
  {"noSetup": true}
  ```
</ParamField>

<ParamField path="noTeardown" type="boolean">
  Skip `teardown()` function.

  ```json theme={null}
  {"noTeardown": true}
  ```
</ParamField>

<ParamField path="linger" type="boolean">
  Keep API server alive after test.

  ```json theme={null}
  {"linger": true}
  ```
</ParamField>

<ParamField path="noUsageReport" type="boolean">
  Disable usage statistics.

  ```json theme={null}
  {"noUsageReport": true}
  ```
</ParamField>

<ParamField path="throw" type="boolean">
  Throw warnings as errors.

  ```json theme={null}
  {"throw": true}
  ```
</ParamField>

### Network Configuration

<ParamField path="blacklistIPs" type="array">
  IP ranges to blacklist.

  ```json theme={null}
  {
    "blacklistIPs": ["10.0.0.0/8", "192.168.0.0/16"]
  }
  ```
</ParamField>

<ParamField path="blockHostnames" type="array">
  Hostname patterns to block.

  ```json theme={null}
  {
    "blockHostnames": ["*.internal.example.com", "localhost"]
  }
  ```
</ParamField>

<ParamField path="dns" type="object">
  DNS resolver configuration.

  ```json theme={null}
  {
    "dns": {
      "ttl": "5m",
      "select": "random",
      "policy": "preferIPv4"
    }
  }
  ```
</ParamField>

### Cloud Configuration

<ParamField path="cloud" type="object">
  Grafana Cloud k6 options.

  ```json theme={null}
  {
    "cloud": {
      "projectID": 12345,
      "name": "My Load Test",
      "distribution": {
        "amazon:us:ashburn": {
          "loadZone": "amazon:us:ashburn",
          "percent": 50
        },
        "amazon:eu:dublin": {
          "loadZone": "amazon:eu:dublin",
          "percent": 50
        }
      }
    }
  }
  ```
</ParamField>

## Complete Example

Here's a comprehensive configuration file example:

```json theme={null}
{
  "scenarios": {
    "load_test": {
      "executor": "ramping-vus",
      "startVUs": 0,
      "stages": [
        { "duration": "2m", "target": 50 },
        { "duration": "5m", "target": 50 },
        { "duration": "2m", "target": 100 },
        { "duration": "5m", "target": 100 },
        { "duration": "2m", "target": 0 }
      ]
    }
  },
  "thresholds": {
    "http_req_duration": ["p(95)<500", "p(99)<1000"],
    "http_req_failed": ["rate<0.01"],
    "checks": ["rate>0.95"]
  },
  "out": [
    "json=results.json",
    "influxdb=http://localhost:8086/k6"
  ],
  "summaryTrendStats": ["avg", "min", "med", "max", "p(90)", "p(95)", "p(99)"],
  "systemTags": ["proto", "status", "method", "url", "name", "group"],
  "insecureSkipTLSVerify": false,
  "noConnectionReuse": false,
  "userAgent": "MyLoadTest/1.0",
  "batch": 20,
  "batchPerHost": 6,
  "maxRedirects": 10,
  "noUsageReport": true,
  "discardResponseBodies": false
}
```

## Best Practices

### Separate Configs for Environments

Create environment-specific configs:

```bash theme={null}
# Development
k6 run --config k6.dev.json script.js

# Staging
k6 run --config k6.staging.json script.js

# Production
k6 run --config k6.prod.json script.js
```

### Use JSON Schema

Validate your config with a JSON schema editor for better error detection.

### Version Control

Commit config files to version control:

```bash theme={null}
git add k6*.json
git commit -m "Add k6 configurations"
```

### Document Custom Settings

Add comments in accompanying README:

```markdown theme={null}
## k6 Configuration

- `k6.smoke.json` - Quick smoke test (1 VU, 1 min)
- `k6.load.json` - Standard load test (100 VUs, 10 min)
- `k6.stress.json` - Stress test (500 VUs, 30 min)
```

### Avoid Secrets

<Warning>
  Never commit secrets to config files. Use environment variables instead.
</Warning>

```json theme={null}
// Bad - token in config
{
  "cloud": {
    "token": "secret-token"
  }
}

// Good - use environment variable
{
  "cloud": {
    "projectID": 12345
  }
}
```

## Schema Validation

While k6 doesn't provide an official JSON schema, the configuration structure mirrors the `lib.Options` Go struct. Invalid options will cause k6 to exit with an error.

## Troubleshooting

### Config Not Loading

If your config isn't being applied:

1. Verify the file exists: `ls -la k6.json`
2. Check JSON syntax: `cat k6.json | jq .`
3. Use explicit path: `k6 run --config ./k6.json script.js`
4. Enable verbose logging: `k6 run --verbose --config k6.json script.js`

### Option Priority

Remember CLI flags override config:

```bash theme={null}
# Config says 10 VUs, CLI says 50 - result is 50 VUs
k6 run --vus 50 --config k6.json script.js
```

### Invalid Options

k6 validates options on startup. Check error messages:

```
ERROR: invalid option: thresholds must be a map of strings to arrays
```

## See Also

* [CLI Options Reference](/cli/options)
* [Environment Variables](/cli/environment-variables)
* [k6 run](/cli/run)