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

# Installation

> Install Bun via npm, Homebrew, Docker, or the official script.

## Overview

Bun ships as a single, dependency-free executable. You can install it on macOS, Linux, and Windows via script, package manager, or Docker.

<Tip>After installation, verify with `bun --version` and `bun --revision`.</Tip>

## Installation

<Tabs>
  <Tab title="macOS & Linux">
    <CodeGroup>
      ```bash curl icon="globe" theme={null}
      curl -fsSL https://bun.com/install | bash
      ```
    </CodeGroup>

    <Note>
      **Linux users** — The `unzip` package is required to install Bun. Install it with `sudo apt install unzip`. Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1. Use `uname -r` to check your kernel version.
    </Note>
  </Tab>

  <Tab title="Windows">
    <CodeGroup>
      ```powershell PowerShell icon="terminal" theme={null}
      powershell -c "irm bun.sh/install.ps1|iex"
      ```
    </CodeGroup>

    <Warning>
      Bun requires Windows 10 version 1809 or higher.
    </Warning>

    For support and discussion, join our **#windows** channel on [Discord](https://bun.com/discord).
  </Tab>

  <Tab title="Package Managers">
    <CodeGroup>
      ```bash npm icon="npm" theme={null}
      npm install -g bun # the last npm command you'll ever need
      ```

      ```bash Homebrew icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/homebrew.svg" theme={null}
      brew install oven-sh/bun/bun
      ```

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

  <Tab title="Docker">
    Bun provides Docker images for Linux x64 and arm64.

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

    ### Image variants

    There are also image variants for different operating systems:

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

To confirm Bun is installed successfully, open a new terminal window and run:

```bash terminal icon="terminal" theme={null}
bun --version
# Example output: 1.x.y

# To see the exact commit of oven-sh/bun you are using
bun --revision
# Example output: 1.x.y+b7982ac13189
```

<Warning>
  If you have Bun installed but see a `command not found` error, you may need to manually add the install directory (`~/.bun/bin`) to your `PATH`.
</Warning>

<Accordion title="Add Bun to your PATH">
  <Tabs>
    <Tab title="macOS & Linux">
      <Steps>
        <Step title="Determine which shell you are using">
          ```bash terminal icon="terminal" theme={null}
          echo $SHELL
          # Possible outputs: /bin/zsh or /bin/bash or /bin/fish
          ```
        </Step>

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

        <Step title="Add the Bun directory to PATH">
          Add the following to your profile:

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

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

    <Tab title="Windows">
      <Steps>
        <Step title="Verify the bun executable is installed correctly">
          ```bash terminal icon="terminal" theme={null}
          & "$env:USERPROFILE\.bun\bin\bun" --version
          ```

          If that command works, but `bun --version` is not recognized, then bun is not added to your system PATH. To fix this, open a PowerShell window and run:

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

        <Step title="Restart your terminal">
          After running the command, restart your terminal and test `bun --version`

          ```bash terminal icon="terminal" theme={null}
          bun --version
          ```
        </Step>
      </Steps>
    </Tab>
  </Tabs>
</Accordion>

***

## Upgrade

Once installed, the binary can self-upgrade:

```bash terminal icon="terminal" theme={null}
bun upgrade
```

<Tip>
  **Homebrew users** <br />
  To avoid conflicts with Homebrew, use `brew upgrade bun` instead.

  **Scoop users** <br />
  To avoid conflicts with Scoop, use `scoop update bun` instead.
</Tip>

***

## Canary builds

[-> View canary build](https://github.com/oven-sh/bun/releases/tag/canary)

Bun automatically releases an (untested) canary build on every commit to `main`. To upgrade to the latest canary build:

```bash terminal icon="terminal" theme={null}
# Upgrade to the latest canary
bun upgrade --canary

# Switch back to stable
bun upgrade --stable
```

Canary builds are useful for testing new features and bug fixes, and help the Bun team fix issues faster. Canary builds automatically upload crash reports to the Bun team.

***

## Install a specific version

Because Bun is a single binary, you can install a specific version by re-running the install script with a version specified.

<Tabs>
  <Tab title="Linux & macOS">
    To install a specific version, pass a git tag to the install script:

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

  <Tab title="Windows">
    On Windows, pass the version number to the PowerShell install script:

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

***

## Direct downloads

To directly download Bun binaries, visit the [GitHub releases page](https://github.com/oven-sh/bun/releases).

### Latest release downloads

<CardGroup cols={2}>
  <Card icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/linux.svg" title="Linux x64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64.zip">
    Standard Linux x64 binary
  </Card>

  <Card icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/linux.svg" title="Linux x64 Baseline" href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-baseline.zip">
    For older CPUs without AVX2
  </Card>

  <Card icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/windows.svg" title="Windows x64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-x64.zip">
    Standard Windows binary
  </Card>

  <Card icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/windows.svg" title="Windows x64 Baseline" href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-x64-baseline.zip">
    For older CPUs without AVX2
  </Card>

  <Card icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/windows.svg" title="Windows ARM64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-aarch64.zip">
    For ARM-based Windows (Snapdragon, etc.)
  </Card>

  <Card icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/apple.svg" title="macOS ARM64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-darwin-aarch64.zip">
    Apple Silicon (M1/M2/M3)
  </Card>

  <Card icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/apple.svg" title="macOS x64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-darwin-x64.zip">
    Intel Mac
  </Card>

  <Card icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/linux.svg" title="Linux ARM64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-aarch64.zip">
    ARM64 Linux systems
  </Card>
</CardGroup>

### Musl builds

For distributions that don't support `glibc` (Alpine Linux, Void Linux, etc.):

* [Linux x64 musl](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-musl.zip)
* [Linux x64 musl baseline](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-musl-baseline.zip)
* [Linux ARM64 musl](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-aarch64-musl.zip)

<Note>
  If you see errors like `bun: /lib/x86_64-linux-gnu/libm.so.6: version GLIBC_2.29 not found`, try the musl build. Bun's
  install script automatically picks the right binary for your system.
</Note>

***

## CPU requirements

Bun has different CPU requirements depending on which binary you use:

<Tabs>
  <Tab title="Standard builds">
    **x64 binaries** target the Haswell CPU architecture (requires AVX and AVX2 instruction sets)

    | Platform | Intel Requirement                | AMD Requirement     |
    | -------- | -------------------------------- | ------------------- |
    | x64      | Haswell (4th gen Core) and newer | Excavator and newer |
  </Tab>

  <Tab title="Baseline builds">
    **x64-baseline binaries** target the Nehalem architecture for older CPUs

    | Platform     | Intel Requirement                | AMD Requirement     |
    | ------------ | -------------------------------- | ------------------- |
    | x64-baseline | Nehalem (1st gen Core) and newer | Bulldozer and newer |

    <Warning>
      Baseline builds run slower and should only be used if you encounter "Illegal Instruction" errors.
    </Warning>
  </Tab>
</Tabs>

<Note>Bun does not support CPUs older than the baseline target, which requires SSE4.2 instruction support. macOS also requires version 13.0 or higher.</Note>

***

## Uninstall

To remove Bun from your system:

<Tabs>
  <Tab title="macOS & Linux">
    ```bash terminal icon="terminal" theme={null}
    rm -rf ~/.bun
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell PowerShell icon="windows" theme={null}
    powershell -c ~/.bun/uninstall.ps1
    ```
  </Tab>

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

      ```bash Homebrew icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/homebrew.svg" theme={null}
      brew uninstall bun
      ```

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