Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 39 ยท Getting Started

Installing Bun

Install Bun on Windows, macOS, Linux, Docker or through npm, check the version, upgrade, pin a version in CI, set up editor types and uninstall cleanly.

Bun is a single executable, so installing it means putting one file on your PATH. There are several ways to do that, and the right one depends on your operating system and whether the install is for your laptop, a CI job or a container. This lesson walks through each method, shows how to confirm it worked, and covers upgrades, pinning versions and editor support.

You do not need Node.js installed to use Bun. If you do have Node, the two live side by side without trouble, because they are separate programs.

Install on macOS and Linux

The official install script downloads the right binary for your CPU and places it in ~/.bun/bin:

Terminal
curl -fsSL https://bun.sh/install | bash

The script also adds that folder to your shell profile (~/.zshrc, ~/.bashrc or similar). Open a new terminal, or run source ~/.zshrc, so the bun command is found.

On macOS with Homebrew:

Terminal
brew tap oven-sh/bun
brew install bun

Linux needs a reasonably recent kernel (5.6 or newer is recommended) and unzip for the script. Both x64 and arm64 builds exist.

Install on Windows

Use PowerShell:

POWERSHELL
powershell -c "irm bun.sh/install.ps1 | iex"

This installs to %USERPROFILE%\.bun\bin and adds it to your user PATH. Open a new terminal window afterwards. Windows 10 version 1809 or newer, or Windows 11, is required. Package managers work too, for example scoop install bun.

If you run Linux tooling on Windows, install Bun inside WSL with the Linux script. The Windows and WSL installations are independent, each with its own cache and global packages.

Install with npm

If Node.js is already on the machine, npm can install Bun globally:

Terminal
npm install -g bun

This is handy on CI images that have Node but not Bun. The npm package downloads the correct native binary for the platform; the bun command that results is the same program as the script install.

Docker

Bun publishes official images. The oven/bun image has the tool pre-installed and is a good base for services:

DOCKERFILE
FROM oven/bun:1
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile
COPY . .
CMD ["bun", "run", "src/index.ts"]

Image tags such as 1, 1.2, canary, alpine, slim and distroless let you trade size for convenience. The Deploy and Compatibility chapter returns to containers in detail.

Check that it works

Terminal
bun --version
bun --revision

bun --version prints something like 1.2.20. --revision adds the git commit the binary was built from, which is useful in bug reports. To see everything the tool can do, run bun --help (covered in the CLI tour).

You can also ask Bun to run a one-liner:

Terminal
bun -e "console.log(2 + 2)"

That prints 4. The -e (or --eval) flag evaluates a string of code, a quick way to test that the runtime itself works.

Upgrading and downgrading

Bun updates itself:

Terminal
bun upgrade                  # latest stable
bun upgrade --canary         # newest build from the main branch
bun upgrade --stable         # return from canary to stable

Canary builds contain the latest fixes but may break. Use them to test a bug fix, not in production. If you installed with Homebrew, npm or Scoop, upgrade through that tool instead so it keeps track.

To install an exact version, for example in CI so builds are reproducible, pass it to the install script:

Terminal
curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.20"

On GitHub Actions the maintained oven-sh/setup-bun action does the same and can read the version from a file:

YAML
- uses: oven-sh/setup-bun@v2
  with:
    bun-version: 1.2.20
- run: bun install --frozen-lockfile
- run: bun test

You can also record the version a project expects in package.json through the packageManager field or in a .bun-version file that the action understands. Pick one convention for the team and write it in the README.

Shell completions

Terminal
bun completions

Run once to install tab completion for commands and scripts in your shell. It is optional but makes bun run <Tab> list the scripts of the current project.

Editor and TypeScript setup

Bun runs TypeScript without checking it, so your editor does the checking. Two things help:

  1. A TypeScript-aware editor such as VS Code (built in), WebStorm or Neovim with a TypeScript language server.
  2. The type definitions for Bun's own globals. A project created with bun init already includes them. In an existing project:
Terminal
bun add -d @types/bun

Then make sure tsconfig.json does not exclude them. Without these types your editor underlines Bun.serve as an unknown name even though it runs fine. The TypeScript and JSX lesson shows a full tsconfig.json.

For debugging, the official Bun for Visual Studio Code extension adds a debugger, a test explorer and bunfig.toml support. It is optional; plain console.log also works everywhere.

Where Bun keeps things

Location Purpose
~/.bun/bin/bun The executable (the Windows path uses %USERPROFILE%)
~/.bun/install/cache Global package cache shared by every project
~/.bun/install/global Packages installed with bun add -g
~/.bunfig.toml Optional user-wide configuration

Knowing these makes troubleshooting easier: a corrupt cache is fixed with bun pm cache rm, and the folder size shows how much disk Bun uses.

Uninstalling

If you installed with the script, delete the folder and remove the PATH line it added to your shell profile:

Terminal
rm -rf ~/.bun

On Windows, delete %USERPROFILE%\.bun and remove it from your user environment variables. If you used Homebrew, npm or Scoop, use brew uninstall bun, npm uninstall -g bun or scoop uninstall bun.

A stand-in check you can run

You cannot run bun --version on this page, but you can see how a program detects which runtime it is running on. Node has process.versions.node and Bun adds a bun entry. This stand-in prints what exists on Node 24:

Node.js Stand-in: detect the runtime (runs on Node 24)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In real Bun, the first line prints true, because process.versions.bun holds your Bun version. Libraries use this check to choose between Bun-specific and Node-compatible code paths.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command prints the installed Bun version?

    bun --version prints the version; bun --revision also prints the git commit.
  2. 2. You installed Bun with the official script. How do you update it?

    bun upgrade replaces the binary with the latest stable release. For Homebrew, npm or Scoop installs, use that tool.
  3. 3. Why does the editor report that Bun is an unknown name in an existing project?

    Bun does not type-check. Your editor needs the @types/bun definitions to know the Bun global.
  4. 4. What is a good way to make CI builds use the same Bun version every time?

    Pinning a specific version, for example with oven-sh/setup-bun, makes builds reproducible.

Summary

  • Install with the official script (macOS, Linux), the PowerShell script (Windows), Homebrew, Scoop, npm or the oven/bun Docker image.
  • Verify with bun --version; update with bun upgrade.
  • Pin an exact version in CI for reproducible builds.
  • Add @types/bun so editors understand Bun's globals.
  • Bun keeps its binary, cache and global packages under ~/.bun; uninstalling is deleting that folder.

Next: Your First Bun Program