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

# 安装

> 使用 npm、Homebrew、Docker 或官方脚本安装 Bun。

## 概述

Bun 以单个无依赖的可执行文件形式发布。在 macOS、Linux 和 Windows 上可通过安装脚本、包管理器或 Docker 进行安装。

<Tip>安装后，使用 `bun --version` 和 `bun --revision` 进行验证。</Tip>

## 安装

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

    <Note>
      **Linux 用户** — 安装 Bun 需要 `unzip` 包（`sudo apt install unzip`）。建议使用内核版本 5.6 或更高版本；Bun 可运行在内核 3.10（RHEL 7）及以上版本，较新的系统调用会优雅降级。使用 `uname -r` 检查你的内核版本。
    </Note>
  </Tab>

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

    <Warning>
      Bun 需要 Windows 10 版本 1809 或更高版本。
    </Warning>

    如需支持和讨论，请加入 [Discord](https://bun.com/discord) 上的 **#windows** 频道。
  </Tab>

  <Tab title="包管理器">
    <CodeGroup>
      ```bash npm icon="npm" theme={null}
      npm install -g bun # 你需要的最后一个 `npm` 命令
      ```

      ```bash Homebrew icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/homebrew.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=fa7dfaea9026d73f26410931c8e8f14d" theme={null}
      brew install oven-sh/bun/bun
      ```

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

  <Tab title="Docker">
    Bun 提供同时支持 Linux x64 和 arm64 的 Docker 镜像。

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

    ### 镜像变体

    Bun 还发布了针对不同操作系统的镜像变体：

    ```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>

要检查 Bun 是否安装成功，打开一个新的终端窗口并运行：

```bash terminal icon="terminal" theme={null}
bun --version
# 输出：1.x.y

# 查看你所使用的 `oven-sh/bun` 的精确提交
bun --revision
# 输出：1.x.y+b7982ac13189
```

<Warning>
  如果你已安装 Bun 但遇到 `command not found` 错误，可能需要手动将安装目录（`~/.bun/bin`）添加到你的 `PATH` 中。
</Warning>

<Accordion title="将 Bun 添加到 PATH">
  <Tabs>
    <Tab title="macOS 和 Linux">
      <Steps>
        <Step title="确定你使用的 shell">
          ```bash terminal icon="terminal" theme={null}
          echo $SHELL
          # /bin/zsh  或 /bin/bash 或 /bin/fish
          ```
        </Step>

        <Step title="打开你的 shell 配置文件">
          * 对于 bash：`~/.bashrc`
          * 对于 zsh：`~/.zshrc`
          * 对于 fish：`~/.config/fish/config.fish`
        </Step>

        <Step title="将 Bun 目录添加到 PATH">
          在配置文件中添加以下行：

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

        <Step title="重新加载 shell 配置">
          ```bash terminal icon="terminal" theme={null}
          source ~/.bashrc  # 或 ~/.zshrc
          ```
        </Step>
      </Steps>
    </Tab>

    <Tab title="Windows">
      <Steps>
        <Step title="确认 bun 二进制文件已正确安装">
          ```bash terminal icon="terminal" theme={null}
          & "$env:USERPROFILE\.bun\bin\bun" --version
          ```

          如果命令运行成功但 `bun --version` 未被识别，说明 bun 未在你的系统 PATH 中。要修复此问题，请打开 PowerShell 终端并运行以下命令：

          ```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="重启你的终端">
          重启你的终端并使用 `bun --version` 进行测试。

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

***

## 升级

安装后，Bun 二进制文件可以自行升级：

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

<Tip>
  **Homebrew 用户** <br />
  为避免与 Homebrew 冲突，请改用 `brew upgrade bun`。

  **Scoop 用户** <br />
  为避免与 Scoop 冲突，请改用 `scoop update bun`。
</Tip>

***

## Canary 构建

[-> 查看 canary 构建](https://github.com/oven-sh/bun/releases/tag/canary)

Bun 会在每次提交到主分支时自动发布一个（未经测试的）canary 构建。要升级到最新的 canary 构建：

```bash terminal icon="terminal" theme={null}
# 升级到最新 canary
bun upgrade --canary

# 切换回稳定版
bun upgrade --stable
```

使用 canary 构建可以在新功能和 Bug 修复发布稳定版之前进行测试。为了帮助 Bun 团队更快地修复 Bug，canary 构建会自动上传崩溃报告。

***

## 安装旧版本

由于 Bun 是单个二进制文件，你可以通过使用特定版本重新运行安装脚本来安装旧版本。

<Tabs>
  <Tab title="Linux 和 macOS">
    要安装特定版本，请将 git 标签传递给安装脚本：

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

  <Tab title="Windows">
    在 Windows 上，将版本号传递给 PowerShell 安装脚本：

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

***

## 直接下载

要直接下载 Bun 二进制文件，请访问 [GitHub 上的 releases 页面](https://github.com/oven-sh/bun/releases)。

### 最新版本下载

<CardGroup cols={2}>
  <Card icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/linux.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=061dc643632570503686c09ca867fd87" title="Linux x64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64.zip" width="216" height="256" data-path="icons/linux.svg">
    标准 Linux x64 二进制文件
  </Card>

  <Card icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/linux.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=061dc643632570503686c09ca867fd87" title="Linux x64 Baseline" href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-baseline.zip" width="216" height="256" data-path="icons/linux.svg">
    适用于不支持 AVX2 的老旧 CPU
  </Card>

  <Card icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/windows.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=5899d4bc0143a451f0e91e1965d0266b" title="Windows x64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-x64.zip" width="88" height="88" data-path="icons/windows.svg">
    标准 Windows 二进制文件
  </Card>

  <Card icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/windows.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=5899d4bc0143a451f0e91e1965d0266b" title="Windows x64 Baseline" href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-x64-baseline.zip" width="88" height="88" data-path="icons/windows.svg">
    适用于不支持 AVX2 的老旧 CPU
  </Card>

  <Card icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/windows.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=5899d4bc0143a451f0e91e1965d0266b" title="Windows ARM64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-aarch64.zip" width="88" height="88" data-path="icons/windows.svg">
    Windows on ARM（Snapdragon 等）
  </Card>

  <Card icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/apple.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=5d4560e9126cc351503441f2963177a2" title="macOS ARM64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-darwin-aarch64.zip" width="842" height="1000" data-path="icons/apple.svg">
    Apple Silicon（M1/M2/M3）
  </Card>

  <Card icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/apple.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=5d4560e9126cc351503441f2963177a2" title="macOS x64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-darwin-x64.zip" width="842" height="1000" data-path="icons/apple.svg">
    Intel Mac
  </Card>

  <Card icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/linux.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=061dc643632570503686c09ca867fd87" title="Linux ARM64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-aarch64.zip" width="216" height="256" data-path="icons/linux.svg">
    ARM64 Linux 系统
  </Card>
</CardGroup>

### Musl 二进制文件

适用于不含 `glibc` 的发行版（Alpine Linux、Void Linux）：

* [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>
  Bun 的 glibc 二进制文件需要 glibc 2.17 或更高版本。如果遇到类似 `bun:
      /lib/x86_64-linux-gnu/libc.so.6: version GLIBC_... not found` 的错误，请尝试使用 musl 二进制文件。Bun 的安装脚本会自动为你的系统选择正确的二进制文件。
</Note>

***

## CPU 要求

CPU 要求取决于你使用的二进制文件：

<Tabs>
  <Tab title="标准构建">
    **x64 二进制文件**针对 Haswell CPU 架构（需要 AVX 和 AVX2 指令）

    | 平台  | Intel 要求               | AMD 要求        |
    | --- | ---------------------- | ------------- |
    | x64 | Haswell（第 4 代 Core）或更新 | Excavator 或更新 |
  </Tab>

  <Tab title="Baseline 构建">
    **x64-baseline 二进制文件**针对 Nehalem 架构，适用于老旧 CPU

    | 平台           | Intel 要求               | AMD 要求        |
    | ------------ | ---------------------- | ------------- |
    | x64-baseline | Nehalem（第 1 代 Core）或更新 | Bulldozer 或更新 |

    <Warning>
      Baseline 构建比正常构建慢。仅在你遇到「Illegal Instruction」错误时使用。
    </Warning>
  </Tab>
</Tabs>

<Note>
  Bun 不支持比 baseline 目标更旧的 CPU，这需要 SSE4.2 扩展。Bun 需要 macOS 13.0 或更高版本。
</Note>

***

## 卸载

要从系统中删除 Bun：

<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="包管理器">
    <CodeGroup>
      ```bash npm icon="npm" theme={null}
      npm uninstall -g bun
      ```

      ```bash Homebrew icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/homebrew.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=fa7dfaea9026d73f26410931c8e8f14d" theme={null}
      brew uninstall bun
      ```

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