k6 archive

Create a self-contained test archive

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

• k6 run - Run a test or archive
• k6 cloud - Run tests in Grafana Cloud
• k6 inspect - Inspect an archive