Skip to main content

​
k6 archive format

A k6 archive is a self-contained bundle that includes your test script and all its dependencies. Archives are useful for:
  • Distributing tests to multiple machines
  • Ensuring consistent test execution across environments
  • Running tests in air-gapped or restricted environments
  • Sharing tests with your team

​
Creating an archive

Use the k6 archive command to create an archive: 
k6 archive script.js
This creates an archive.tar file containing:
  • Your test script
  • All imported modules and dependencies
  • Metadata about the test

​
Specify output file

k6 archive script.js -O my-test.tar

​
Include external files

If your test uses open() to load external files, k6 automatically includes them in the archive: 
import { SharedArray } from 'k6/data';

const data = new SharedArray('users', function () {
  return JSON.parse(open('./users.json'));
});

​
Running from an archive

Execute tests directly from an archive: 
k6 run archive.tar
You can still override options: 
k6 run archive.tar --vus 100 --duration 5m

​
Archive structure

A k6 archive is a tar file with this structure: 
archive.tar
├── metadata.json       # Test metadata and options
├── data               # Test script and dependencies
│   ├── script.js
│   ├── users.json
│   └── node_modules/
└── ...

​
Metadata

The metadata.json file contains:
  • Test options (VUs, duration, thresholds, etc.)
  • Script filename
  • Environment information
  • k6 version used to create the archive

​
Use cases

Distributed testing

Create an archive once and distribute it to multiple test runners for consistent execution.

CI/CD pipelines

Build archives as artifacts and run them in different stages of your pipeline.

Air-gapped environments

Transfer archives to restricted networks where dependencies can’t be downloaded.

Version control

Store archives alongside your code to ensure reproducible test runs.

​
Example workflow

1

Create the archive

Build your test with all dependencies:
k6 archive test-script.js -O load-test-v1.tar
2

Distribute the archive

Copy the archive to your test runners:
scp load-test-v1.tar test-runner-1:/tests/
scp load-test-v1.tar test-runner-2:/tests/
3

Run on multiple machines

Execute the same archive on all runners:
# On test-runner-1
k6 run load-test-v1.tar

# On test-runner-2
k6 run load-test-v1.tar

​
Best practices

Version your archives with meaningful names like api-test-v1.2.3.tar to track changes over time.
Only include necessary dependencies. Large archives take longer to transfer and extract.
Include a README with the archive specifying any external requirements or configuration needed.
Always test your archive locally before distributing it to ensure all dependencies are included.
Archives work well with environment variables for configuration:
BASE_URL=https://prod.example.com k6 run archive.tar

​
Limitations

Archives are created for a specific k6 version. Running an archive with a different k6 version may cause compatibility issues.
  • Archives are not compressed by default (use gzip if needed)
  • Binary extensions are not included in archives
  • Archives contain absolute file paths from creation time

Distributed tests

Running tests across multiple machines

Automated testing

Integrating k6 with CI/CD

Build docs developers (and LLMs) love

Get started for freeTalk to us