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

# Installation

> Install Bun on macOS, Linux, or Windows using the install script, a package manager, or Docker.

Bun ships as a single, dependency-free executable. Pick the install method that fits your platform.

<Tip>After installation, verify it worked by running `bun --version` in a new terminal window.</Tip>

## Install Bun

<Tabs>
  <Tab title="macOS & Linux">
    Run the official install script:

    ```bash theme={null}
    curl -fsSL https://bun.com/install | bash
    ```

    The script downloads the correct binary for your system, places it in `~/.bun/bin`, and adds it to your `PATH`.

    <Note>
      **Linux users** — the `unzip` package is required. Install it first with `sudo apt install unzip` (Debian/Ubuntu) or the equivalent for your distro. Kernel version 5.6 or higher is strongly recommended; 5.1 is the minimum. Check with `uname -r`.
    </Note>
  </Tab>

  <Tab title="Windows">
    Run the install script in PowerShell:

    ```powershell theme={null}
    powershell -c "irm bun.sh/install.ps1 | iex"
    ```

    <Warning>
      Bun requires Windows 10 version 1809 or later. For the best experience on Windows, use [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/install) (Windows Subsystem for Linux) and install Bun inside the Linux environment.
    </Warning>
  </Tab>

  <Tab title="Package managers">
    <CodeGroup>
      ```bash npm theme={null}
      npm install -g bun
      ```

      ```bash Homebrew theme={null}
      brew install oven-sh/bun/bun
      ```

      ```bash Scoop theme={null}
      scoop install bun
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Docker">
    Bun provides an official Docker image for Linux x64 and arm64:

    ```bash theme={null}
    docker pull oven/bun
    docker run --rm --init --ulimit memlock=-1:-1 oven/bun
    ```

    Several image variants are available:

    ```bash theme={null}
    docker pull oven/bun:debian
    docker pull oven/bun:slim
    docker pull oven/bun:distroless
    docker pull oven/bun:alpine
    ```
  </Tab>
</Tabs>

## Verify the installation

Open a **new** terminal window and run:

```bash theme={null}
bun --version
# 1.x.y

bun --revision
# 1.x.y+b7982ac13189
```

`bun --revision` shows the exact commit of `oven-sh/bun` that you're running, which is useful when reporting bugs.

<Warning>
  If you see `command not found`, your shell may not have picked up the updated `PATH`. Open a new terminal window, or manually add `~/.bun/bin` to your `PATH` (see below).
</Warning>

<Accordion title="Add Bun to your PATH manually">
  <Tabs>
    <Tab title="macOS & Linux">
      <Steps>
        <Step title="Find your shell">
          ```bash theme={null}
          echo $SHELL
          # /bin/zsh  or  /bin/bash  or  /bin/fish
          ```
        </Step>

        <Step title="Open your shell config file">
          * bash: `~/.bashrc`
          * zsh: `~/.zshrc`
          * fish: `~/.config/fish/config.fish`
        </Step>

        <Step title="Add the Bun directory">
          Add these lines to your config file:

          ```bash theme={null}
          export BUN_INSTALL="$HOME/.bun"
          export PATH="$BUN_INSTALL/bin:$PATH"
          ```
        </Step>

        <Step title="Reload your config">
          ```bash theme={null}
          source ~/.zshrc   # or ~/.bashrc
          ```
        </Step>
      </Steps>
    </Tab>

    <Tab title="Windows">
      <Steps>
        <Step title="Check the binary is there">
          ```powershell theme={null}
          & "$env:USERPROFILE\.bun\bin\bun" --version
          ```

          If this works but `bun --version` doesn't, Bun isn't on your `PATH`.
        </Step>

        <Step title="Add Bun to your PATH">
          Run this in PowerShell to update your user `PATH` permanently:

          ```powershell theme={null}
          [System.Environment]::SetEnvironmentVariable(
            "Path",
            [System.Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.bun\bin",
            [System.EnvironmentVariableTarget]::User
          )
          ```
        </Step>

        <Step title="Restart your terminal">
          Close and reopen your terminal, then verify with `bun --version`.
        </Step>
      </Steps>
    </Tab>
  </Tabs>
</Accordion>

## Upgrade

Once installed, Bun can upgrade itself:

```bash theme={null}
bun upgrade
```

<Tip>
  **Homebrew users** — use `brew upgrade bun` to avoid conflicts with Homebrew's version tracking.

  **Scoop users** — use `scoop update bun` instead.
</Tip>

To upgrade to the latest canary build (built from every commit to `main`):

```bash theme={null}
bun upgrade --canary

# Switch back to the latest stable release
bun upgrade --stable
```

<Note>
  Canary builds are untested pre-releases. They automatically upload crash reports to the Bun team to help fix bugs faster.
</Note>

## Install a specific version

<Tabs>
  <Tab title="macOS & Linux">
    Pass the git tag to the install script:

    ```bash theme={null}
    curl -fsSL https://bun.com/install | bash -s "bun-v1.3.3"
    ```
  </Tab>

  <Tab title="Windows">
    Pass the version number to the PowerShell script:

    ```powershell theme={null}
    iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.3.3"
    ```
  </Tab>
</Tabs>

## Supported platforms

| Platform | Architecture | Notes                                       |
| -------- | ------------ | ------------------------------------------- |
| macOS    | x64, arm64   | Requires macOS 13.0 or later                |
| Linux    | x64, arm64   | Kernel 5.6+ recommended; 5.1 minimum        |
| Windows  | x64          | Windows 10 1809+; WSL 2 recommended         |
| Docker   | x64, arm64   | Official images at `oven/bun` on Docker Hub |

### CPU requirements

The standard x64 binary targets the Haswell architecture and requires **AVX2** support (Intel 4th-gen Core / AMD Excavator or newer). If you see an "Illegal Instruction" error on older hardware, use the baseline build instead:

```bash theme={null}
curl -fsSL https://bun.com/install | bash -s "bun-v$(bun --version)-baseline"
```

The baseline build targets Nehalem (Intel 1st-gen Core / AMD Bulldozer) and requires only SSE4.2.

## Uninstall

<Tabs>
  <Tab title="macOS & Linux">
    Remove the `~/.bun` directory:

    ```bash theme={null}
    rm -rf ~/.bun
    ```

    Then remove the `BUN_INSTALL` and `PATH` lines from your shell config file.
  </Tab>

  <Tab title="Windows">
    Run the bundled uninstall script:

    ```powershell theme={null}
    powershell -c "~\.bun\uninstall.ps1"
    ```
  </Tab>

  <Tab title="Package managers">
    <CodeGroup>
      ```bash npm theme={null}
      npm uninstall -g bun
      ```

      ```bash Homebrew theme={null}
      brew uninstall bun
      ```

      ```bash Scoop theme={null}
      scoop uninstall bun
      ```
    </CodeGroup>
  </Tab>
</Tabs>