> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/grafana/k6/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Extensions

> How to build and use k6 with xk6 extensions

To use k6 extensions, you need to build a custom k6 binary that includes the extensions you want. This is done using xk6, the k6 extension builder.

## Prerequisites

* Go 1.22 or later
* Git
* Basic command-line knowledge

<Note>
  You don't need to write Go code to use extensions, only to build k6 with them included.
</Note>

## Installing xk6

Install xk6 using Go:

```bash theme={null}
go install go.k6.io/xk6/cmd/xk6@latest
```

Verify installation:

```bash theme={null}
xk6 version
```

## Building k6 with Extensions

Build k6 with one or more extensions:

```bash theme={null}
xk6 build --with github.com/grafana/xk6-redis@latest
```

This creates a `k6` binary in the current directory with the Redis extension included.

### Multiple Extensions

Include multiple extensions in a single build:

```bash theme={null}
xk6 build \
  --with github.com/grafana/xk6-redis@latest \
  --with github.com/grafana/xk6-kafka@latest \
  --with github.com/grafana/xk6-sql@latest
```

<Tip>
  You can specify any number of extensions in a single build command.
</Tip>

### Specific Versions

Pin extensions to specific versions for reproducibility:

```bash theme={null}
xk6 build --with github.com/grafana/xk6-redis@v0.2.0
```

Use Git references:

```bash theme={null}
xk6 build --with github.com/user/xk6-custom@main
xk6 build --with github.com/user/xk6-custom@feature-branch
xk6 build --with github.com/user/xk6-custom@abc123
```

### Local Development

Use local extension code during development:

```bash theme={null}
xk6 build --with github.com/user/xk6-myext=/path/to/local/xk6-myext
```

This is useful when:

* Developing extensions
* Testing unreleased changes
* Making local modifications

## Output Location

By default, xk6 creates the binary in the current directory. Specify a different location:

```bash theme={null}
xk6 build --output /usr/local/bin/k6 --with github.com/grafana/xk6-redis@latest
```

<Warning>
  You may need `sudo` to write to system directories like `/usr/local/bin`.
</Warning>

## Using Extensions in Tests

Once you've built k6 with extensions, use them in your test scripts.

### JavaScript Extensions

Import JavaScript extensions from the `k6/x/` namespace:

```javascript theme={null}
import redis from 'k6/x/redis';
import sql from 'k6/x/sql';

export default function () {
  // Use extension functionality
  const client = redis.connect('localhost:6379');
  client.set('key', 'value');
}
```

The import name matches the extension's registered name.

### Output Extensions

Use output extensions with the `--out` flag:

```bash theme={null}
./k6 run --out kafka=localhost:9092 script.js
```

Pass configuration:

```bash theme={null}
./k6 run --out myoutput=config-value script.js
```

Or via script options:

```javascript theme={null}
export const options = {
  ext: {
    kafka: {
      brokers: ['localhost:9092'],
      topic: 'k6-metrics',
    },
  },
};
```

### Subcommand Extensions

If an extension adds a subcommand, use it like any k6 command:

```bash theme={null}
./k6 dashboard run script.js
```

## Verifying Extensions

Check which extensions are included in your build:

```bash theme={null}
./k6 version
```

Output shows k6 version and all compiled extensions:

```
k6 v0.50.0 (commit/abc123, go1.22.1, linux/amd64)
Extensions:
  github.com/grafana/xk6-redis v0.2.0
  github.com/grafana/xk6-kafka v0.7.0
```

<Note>
  If an extension doesn't appear, it wasn't properly included during the build.
</Note>

## Common Extension Use Cases

### Testing Databases

```bash theme={null}
xk6 build --with github.com/grafana/xk6-sql@latest
```

```javascript theme={null}
import sql from 'k6/x/sql';

const db = sql.open('postgres', 'connection-string');

export default function () {
  const results = db.query('SELECT * FROM users LIMIT 10');
  console.log(results);
}
```

### Testing Message Queues

```bash theme={null}
xk6 build --with github.com/mostafa/xk6-kafka@latest
```

```javascript theme={null}
import { Writer } from 'k6/x/kafka';

const writer = new Writer({
  brokers: ['localhost:9092'],
  topic: 'test-topic',
});

export default function () {
  writer.produce({
    messages: [{ value: 'test message' }],
  });
}
```

### Browser Testing

```bash theme={null}
xk6 build --with github.com/grafana/xk6-browser@latest
```

```javascript theme={null}
import { browser } from 'k6/x/browser';

export default async function () {
  const page = browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'screenshot.png' });
  page.close();
}
```

### Custom Outputs

```bash theme={null}
xk6 build --with github.com/user/xk6-output-custom@latest
```

```bash theme={null}
./k6 run --out custom=endpoint script.js
```

## Environment-Specific Builds

Create different builds for different environments:

### Development

```bash theme={null}
xk6 build \
  --with github.com/grafana/xk6-dashboard@latest \
  --output k6-dev
```

### Production

```bash theme={null}
xk6 build \
  --with github.com/grafana/xk6-output-prometheus-remote@latest \
  --with github.com/grafana/xk6-kubernetes@latest \
  --output k6-prod
```

## Automation

### Build Script

Create a build script for consistent builds:

```bash theme={null}
#!/bin/bash
# build-k6.sh

set -e

K6_VERSION="v0.50.0"
OUTPUT="./k6"

xk6 build "$K6_VERSION" \
  --output "$OUTPUT" \
  --with github.com/grafana/xk6-redis@latest \
  --with github.com/grafana/xk6-kafka@latest \
  --with github.com/grafana/xk6-sql@latest

echo "k6 built successfully: $OUTPUT"
./k6 version
```

Make it executable and run:

```bash theme={null}
chmod +x build-k6.sh
./build-k6.sh
```

### Docker

Create a Dockerfile with extensions:

```dockerfile theme={null}
FROM golang:1.22-alpine as builder

RUN go install go.k6.io/xk6/cmd/xk6@latest

RUN xk6 build \
  --with github.com/grafana/xk6-redis@latest \
  --with github.com/grafana/xk6-kafka@latest \
  --output /k6

FROM alpine:latest
COPY --from=builder /k6 /usr/bin/k6

ENTRYPOINT ["k6"]
```

Build and use:

```bash theme={null}
docker build -t k6-custom .
docker run -v $(pwd):/scripts k6-custom run /scripts/test.js
```

<Tip>
  Using Docker ensures consistent builds across different environments and team members.
</Tip>

## Troubleshooting

### Build Failures

If the build fails:

1. **Check Go version**: Ensure Go 1.22+
   ```bash theme={null}
   go version
   ```

2. **Verify extension exists**: Check the repository URL
   ```bash theme={null}
   git ls-remote https://github.com/user/xk6-extension
   ```

3. **Check version compatibility**: Some extensions require specific k6 versions

4. **Clear Go cache**:
   ```bash theme={null}
   go clean -modcache
   ```

### Import Errors

If JavaScript imports fail:

1. **Verify extension is included**:
   ```bash theme={null}
   ./k6 version
   ```

2. **Check import path**: Must use `k6/x/` namespace

3. **Rebuild**: Ensure you're using the custom binary

### Extension Not Found

If an extension doesn't appear:

1. **Check registration**: Extension must call `ext.Register()` in `init()`
2. **Rebuild with verbose**:
   ```bash theme={null}
   xk6 build -v --with github.com/user/xk6-ext@latest
   ```
3. **Check extension documentation**: Some extensions have special requirements

## Finding Extensions

Discover extensions:

* **k6 Documentation**: [https://k6.io/docs/extensions/](https://k6.io/docs/extensions/)
* **GitHub Topics**: [https://github.com/topics/xk6](https://github.com/topics/xk6)
* **k6 Community**: [https://community.grafana.com/c/grafana-k6/](https://community.grafana.com/c/grafana-k6/)
* **Awesome k6**: [https://github.com/grafana/awesome-k6](https://github.com/grafana/awesome-k6)

<Note>
  Not all extensions are officially supported by Grafana. Community extensions may have varying quality and maintenance levels.
</Note>

## Best Practices

<Steps>
  ### Pin Versions

  Use specific versions in production for reproducibility:

  ```bash theme={null}
  xk6 build --with github.com/user/xk6-ext@v1.2.3
  ```

  ### Document Your Build

  Keep a record of which extensions and versions you're using.

  ### Test Your Build

  Verify all extensions work after building:

  ```bash theme={null}
  ./k6 version
  ./k6 run test-extensions.js
  ```

  ### Automate Builds

  Use scripts or CI/CD to ensure consistent builds.

  ### Keep Extensions Updated

  Regularly check for extension updates and security fixes.
</Steps>

## Next Steps

* [Extensions Overview](/extensions/overview) - Understand extension types
* [Creating Extensions](/extensions/creating-extensions) - Build your own
* [Creating Custom Outputs](/results/custom-outputs) - Specialized output guide