---
title: "Feature flags | Grafana k6 documentation"
description: "Try experimental k6 capabilities before they become the default."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Feature flags

Feature flags let you try k6 capabilities before they’re on by default. When a feature reaches general availability, it becomes the default and k6 removes the flag.

Unlike operational configuration like `K6_WEB_DASHBOARD`, flags are temporary. Operational config stays user-controllable indefinitely; flags get removed once their behavior is the default.

## Discover available flags

The set of flags changes across k6 releases: some get promoted to defaults and disappear, new ones are added. Check which flags your k6 version supports before enabling one.

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
k6 features
```

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
FEATURE             LIFECYCLE      DESCRIPTION
native-histograms   Experimental   Use native histograms for trend metrics
```

Add `--json` to get machine-readable output, useful for scripting — for example, checking in CI whether a specific flag is available before enabling it:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
k6 features --json
```

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
[
  {
    "feature": "native-histograms",
    "lifecycle": "Experimental",
    "description": "Use native histograms for trend metrics"
  }
]
```

## Enabling flags

k6 supports three ways to enable flags. Pick the one that fits your workflow.

### CLI flag

Use `--features` to enable a flag for a single run, without touching your config or environment:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
k6 run --features native-histograms script.js
```

Separate multiple flags with commas:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
k6 run --features native-histograms,other-flag script.js
```

### Environment variable

Use `K6_FEATURES` when your CI pipeline or shell environment controls which features are active, without changing your script or config file:

Bash windows powershell

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
K6_FEATURES=native-histograms k6 run script.js
```

windows ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```windows
set "K6_FEATURES=native-histograms" && k6 run script.js
```

powershell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```powershell
$env:K6_FEATURES="native-histograms"; k6 run script.js
```

Separate multiple flags with commas: `K6_FEATURES=native-histograms,other-flag`.

### JSON config file

Put flags in a config file to version-control them alongside your test suite and share them with your team:

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "features": ["native-histograms"]
}
```

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
k6 run --config config.json script.js
```

## Precedence

If you set flags in more than one place, CLI wins over the environment variable, which wins over the config file. The winning source is used as-is; k6 ignores the others entirely. For example, if you pass `--features`, k6 ignores `K6_FEATURES` for that run.

## Lifecycle stages

A flag’s lifecycle stage tells you how stable it is and when to clean it up. Check the stage before relying on a flag in production or long-running CI.

Expand table

| Stage          | Behavior                                                                       |
|----------------|--------------------------------------------------------------------------------|
| `Experimental` | Off by default. Enable to try it. May change or be removed.                    |
| `GA`           | On by default. Passing the flag logs a reminder to remove it from your config. |
| `Deprecated`   | Off by default. Removed in a future release.                                   |

> Note
> 
> If you pass a flag k6 doesn’t recognize (a typo or a flag removed after its grace period), k6 logs an `ERROR` and the run continues. Watch your logs — the flag is not applied.

## Migrate from legacy environment variables

Some features previously used their own environment variables. For example, `K6_PROMETHEUS_RW_TREND_AS_NATIVE_HISTOGRAM` maps to the `native-histograms` flag. The old variable still works but logs a deprecation warning and will be removed in a future release. Switch to `K6_FEATURES=native-histograms` or `--features native-histograms` to avoid breakage when it’s gone.

## Observability

If you’re comparing test results across runs (for example, checking whether a feature improved tail latency), you need to know which features were active. k6 tags every metric sample with the active flags so you can filter and compare in your output.

While a flag is active, every metric sample carries a tag `k6_feature_<name>="true"` (hyphens become underscores, for example `k6_feature_native_histograms="true"`).

k6 also includes active flags in [usage telemetry](/docs/k6/next/set-up/usage-collection/).

## Running on Grafana Cloud

Feature flags work the same when you run tests through [Grafana Cloud k6](/docs/grafana-cloud/testing/k6/). Set them with `--features`, `K6_FEATURES`, or a config file. Your test runs on the cloud with the same features active as locally.

## Read more

- [k6 options](/docs/k6/next/using-k6/k6-options/)
- [Usage collection](/docs/k6/next/set-up/usage-collection/)