k6.wiki

If you are coming to Windows from a Linux or macOS developer workspace, one of the first roadblocks you will hit is how shell environments handle environment variables. On Unix-style shells, you can easily pass inline variables directly in front of your execution command, like VAR=val k6 run script.js. This scope is temporary and only exists for the duration of that specific process. But on Windows terminals, trying this syntax will result in shell errors.

Windows shells handle environment variables statefully, meaning they persist across your entire terminal session unless explicitly cleared. Let us look at how variables behave in PowerShell and Command Prompt, and map out the cleanest way to manage execution state.

PowerShell vs. Windows Command Prompt (CMD)

To pass parameters to your k6 runtimes, you must adapt your syntax to the specific terminal shell you are running. Let us compare the syntax rules across the two primary Windows shells:

Because these environment variables are stateful, they remain active in your terminal tab until you close it or explicitly wipe them using the removal commands. If you run a test, change your script, and run it again in the same tab, k6 will continue to read the old environment variables. This is a common point of confusion that leads to head scratching and debugging errors.

The Platform-Agnostic Alternative: Command-Line Switches

To avoid managing stateful variables inside your shell sessions, k6 offers a highly elegant alternative: the -e / --env command-line switch. This parameter switch behaves identically across all Windows, Linux, and macOS shells, passing key-value variables directly into k6's execution container without altering your global shell session:

# Works perfectly in both PowerShell and CMD without altering shell state
k6 run --env BASE_URL=https://quickpizza.grafana.com --env USER_ID=102 main.js

Inside your JavaScript script, you can access these variables easily using the global __ENV execution object:

// Read values passed via --env switches or global environment variables
const targetUrl = __ENV.BASE_URL;
const selectedUser = __ENV.USER_ID;

By leveraging the --env switch, you keep your shell sessions clean, prevent state leakage between subsequent runs, and write scripts that execute identically across diverse developer environments and automated runner tasks.

Now that you know how to configure execution scopes on Windows, learn how to compile custom executables in Building custom k6.exe Binaries on Windows using xk6. If you want to design a modular framework around these scripts, see Architecting an Enterprise k6 Framework on Windows. If you want to see how to execute workloads and capture compressed HTML outputs, check out k6 Workload Execution and static Gzip HTML Report Generation on Windows.