> ## 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.

# Installation

> Install k6 on Linux, macOS, Windows, or Docker

## Overview

k6 is available for all major platforms. Choose your preferred installation method below.

<CardGroup cols={2}>
  <Card title="Linux" icon="linux">
    Install via package managers or download binaries
  </Card>

  <Card title="macOS" icon="apple">
    Install with Homebrew or download directly
  </Card>

  <Card title="Windows" icon="windows">
    Install with package managers or executables
  </Card>

  <Card title="Docker" icon="docker">
    Run k6 in containers without installation
  </Card>
</CardGroup>

## Installation methods

<Tabs>
  <Tab title="macOS">
    ### Using Homebrew

    The easiest way to install k6 on macOS is using Homebrew:

    ```bash theme={null}
    brew install k6
    ```

    ### Verify installation

    Check that k6 is installed correctly:

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

    <Tip>
      Homebrew automatically handles updates. Run `brew upgrade k6` to get the latest version.
    </Tip>
  </Tab>

  <Tab title="Linux">
    ### Debian/Ubuntu

    Install k6 using the apt package manager:

    ```bash theme={null}
    sudo gpg -k
    sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
    echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
    sudo apt-get update
    sudo apt-get install k6
    ```

    ### Fedora/CentOS/RedHat

    Install using the yum package manager:

    ```bash theme={null}
    sudo dnf install https://dl.k6.io/rpm/repo.rpm
    sudo dnf install k6
    ```

    ### Verify installation

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

    <Note>
      For other Linux distributions, you can download pre-compiled binaries from the [GitHub releases page](https://github.com/grafana/k6/releases).
    </Note>
  </Tab>

  <Tab title="Windows">
    ### Using Chocolatey

    If you have [Chocolatey](https://chocolatey.org/) installed:

    ```powershell theme={null}
    choco install k6
    ```

    ### Using Windows Package Manager

    If you have [winget](https://docs.microsoft.com/en-us/windows/package-manager/winget/) installed:

    ```powershell theme={null}
    winget install k6 --source winget
    ```

    ### Manual installation

    <Steps>
      <Step title="Download the installer">
        Download the latest `.msi` installer from the [k6 releases page](https://github.com/grafana/k6/releases).
      </Step>

      <Step title="Run the installer">
        Double-click the downloaded `.msi` file and follow the installation wizard.
      </Step>

      <Step title="Verify installation">
        Open Command Prompt or PowerShell and run:

        ```powershell theme={null}
        k6 version
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Docker">
    ### Using Docker

    Run k6 directly from a Docker container without installing:

    ```bash theme={null}
    docker pull grafana/k6:latest
    ```

    ### Run a test

    To run a test script with Docker:

    ```bash theme={null}
    docker run --rm -v $(pwd):/scripts grafana/k6:latest run /scripts/test.js
    ```

    ### Docker Compose

    For more complex setups, use Docker Compose. Create a `docker-compose.yml` file:

    ```yaml theme={null}
    version: '3.8'
    services:
      k6:
        image: grafana/k6:latest
        volumes:
          - ./scripts:/scripts
        command: run /scripts/test.js
    ```

    Then run:

    ```bash theme={null}
    docker-compose up
    ```

    <Tip>
      Docker is perfect for CI/CD environments where you want consistent, reproducible test execution.
    </Tip>
  </Tab>
</Tabs>

## Build from source

For developers who want to build k6 from source:

<Steps>
  <Step title="Install Go">
    Make sure you have [Go](https://golang.org/doc/install) installed (version 1.21 or later).

    ```bash theme={null}
    go version
    ```
  </Step>

  <Step title="Clone the repository">
    Clone the k6 repository from GitHub:

    ```bash theme={null}
    git clone https://github.com/grafana/k6.git
    cd k6
    ```
  </Step>

  <Step title="Build k6">
    Build the k6 binary:

    ```bash theme={null}
    go build -o k6 .
    ```
  </Step>

  <Step title="Verify the build">
    Check that k6 was built successfully:

    ```bash theme={null}
    ./k6 version
    ```
  </Step>
</Steps>

<Note>
  Building from source gives you access to the latest features and allows you to customize k6 for your specific needs.
</Note>

## Install k6 extensions

k6 has a rich ecosystem of extensions that add support for new protocols and features:

### Using xk6

[xk6](https://github.com/grafana/xk6) is the official tool for building k6 with extensions:

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

# Build k6 with extensions
xk6 build --with github.com/grafana/xk6-sql
```

<Tip>
  Explore available extensions at the [k6 extensions page](https://grafana.com/docs/k6/latest/extensions/explore).
</Tip>

## Verify your installation

After installation, verify k6 is working correctly:

<CodeGroup>
  ```bash Check version theme={null}
  k6 version
  ```

  ```bash Run help theme={null}
  k6 --help
  ```

  ```bash Test with simple script theme={null}
  k6 run --vus 10 --duration 30s https://quickpizza.grafana.com
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="k6 command not found">
    If you get a "command not found" error:

    * Make sure k6 is in your PATH
    * Try closing and reopening your terminal
    * On Windows, restart Command Prompt or PowerShell after installation
  </Accordion>

  <Accordion title="Permission denied on Linux/macOS">
    If you encounter permission errors:

    ```bash theme={null}
    sudo chmod +x /usr/local/bin/k6
    ```

    Or use `sudo` when running installation commands.
  </Accordion>

  <Accordion title="Docker volume mounting issues">
    If your test scripts aren't being found in Docker:

    * Make sure you're using absolute paths or `$(pwd)`
    * On Windows, use `${PWD}` in PowerShell or `%cd%` in Command Prompt
    * Check that the script file exists in the mounted directory
  </Accordion>
</AccordionGroup>

## Next steps

<Card title="Quick start guide" icon="rocket" href="/quickstart">
  Now that k6 is installed, let's run your first load test!
</Card>

<Warning>
  Always verify your k6 installation before running production tests. Use `k6 version` to ensure you're running the expected version.
</Warning>