Skip to main content

​
k6 archive

Create a fully self-contained test archive that can be executed identically elsewhere.

​
Synopsis

k6 archive [flags] <script>

​
Description

The k6 archive command creates a tarball (.tar file) containing:
  • The test script
  • All imported modules and dependencies
  • Test configuration and options
  • Environment variables (unless excluded)
This archive is completely self-contained and can be executed on any system with k6 installed, ensuring consistent test execution across different environments.

​
Arguments

​
script
string
required
Path to the test script file to archive

​
Examples

# Archive a test run
k6 archive -u 10 -d 10s -O myarchive.tar script.js

# Run the resulting archive
k6 run myarchive.tar

# Create an archive without environment variables
k6 archive --exclude-env-vars -O myarchive.tar script.js

# Archive and output to stdout
k6 archive -O - script.js > myarchive.tar

​
Flags

​
-O, --archive-out
string
default:"archive.tar"
Archive output filename. Use - to output to stdout.
​
--exclude-env-vars
boolean
Do not embed any environment variables (either from --env or the actual environment) in the archive metadata

​
Test Configuration Flags

All standard test execution flags are available to configure the archived test:
​
-u, --vus
int
default:"1"
Number of virtual users
​
-d, --duration
duration
Test duration
​
-i, --iterations
int
Total iteration limit
​
-s, --stage
string[]
Add execution stages
​
--execution-segment
string
Execution segment for distributed testing

​
Runtime Options

​
-e, --env
string[]
Add/override environment variable with VAR=value
​
--include-system-env-vars
boolean
Include system environment variables
​
--compatibility-mode
string
default:"extended"
JavaScript compatibility mode
All other options from k6 run are also available. See k6 run for the complete list.

​
Archive Contents

A k6 archive contains:
  1. Test Script - The main JavaScript file
  2. Dependencies - All imported modules and files
  3. Configuration - Consolidated options from all sources
  4. Environment Variables - Runtime environment (unless excluded)
  5. Metadata - Version information and execution context

​
Use Cases

​
Reproducible Testing

Create an archive to ensure the exact same test can be run later: 
k6 archive -u 100 -d 5m -O prod-test.tar script.js
# Later or on another machine:
k6 run prod-test.tar

​
Distributed Execution

Create archives for execution across multiple machines: 
# Create archive for first segment
k6 archive --execution-segment "0:1/3" -O segment1.tar script.js

# Create archive for second segment  
k6 archive --execution-segment "1/3:2/3" -O segment2.tar script.js

# Create archive for third segment
k6 archive --execution-segment "2/3:1" -O segment3.tar script.js

​
CI/CD Pipelines

Archive tests in one pipeline stage, execute in another: 
# Build stage
k6 archive --exclude-env-vars -O test.tar script.js

# Test stage (different environment)
k6 run -e API_URL=$PROD_URL test.tar

​
Cloud Execution

Archives can be uploaded and executed in Grafana Cloud: 
k6 archive -O test.tar script.js
k6 cloud run test.tar

​
Security Considerations

By default, archives include environment variables. Use --exclude-env-vars if the archive will be shared or stored in version control.
Environment variables may contain sensitive information like:
  • API keys
  • Passwords
  • Tokens
  • Internal URLs
Always review what’s being archived when dealing with sensitive data.

​
Exit Codes

  • 0 - Archive created successfully
  • Non-zero - Error occurred

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us