Bun Installation

This chapter introduces how to install Bun on different operating systems, as well as verification and configuration after installation.

System Requirements

Bun supports the following operating systems:

Operating System	Version Requirements	Architecture
macOS	10.14+	x64, ARM64 (M1/M2)
Linux	glibc 2.17+	x64, ARM64
Windows	Windows 10+	x64
WSL	Ubuntu 20.04+	x64, ARM64

macOS / Linux Installation

Method 1: Official Installation Script (Recommended)

Open terminal and run the following command:

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

After installation, restart terminal or run:

source ~/.bashrc  # Linux (bash)
source ~/.zshrc   # macOS (zsh)

Method 2: Using Homebrew (macOS)

brew install oven-sh/bun/bun

Method 3: Using npm

If Node.js is already installed:

npm install -g bun

Method 4: Using Proto

proto install bun

Windows Installation

Method 1: PowerShell Installation (Recommended)

Open PowerShell as administrator:

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

Method 2: Using Scoop

scoop install bun

Method 3: Using npm

npm install -g bun

Method 4: Via WSL

Use Linux installation method in WSL:

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

Verifying Installation

After installation, verify Bun is correctly installed:

# View version
bun --version

# Example output
# 1.1.0

# View help
bun --help

Quick Test

Create a test file:

// test.js
console.log("Hello from Bun!");
console.log("Bun version:", Bun.version);

Run the test:

bun test.js

Output:

Hello from Bun!
Bun version: 1.1.0

Updating Bun

Using Built-in Command

bun upgrade

Updating to Specific Version

bun upgrade --version 1.1.0

Updating to Latest Beta

bun upgrade --canary

Uninstalling Bun

macOS / Linux

# Delete Bun executable
rm -rf ~/.bun

# Remove PATH from shell config
# Edit ~/.bashrc or ~/.zshrc, remove bun-related lines

Windows

# Delete Bun directory
Remove-Item -Recurse -Force $env:USERPROFILE\.bun

# Remove from environment variables PATH

Uninstall via Package Manager

# Homebrew
brew uninstall bun

# Scoop
scoop uninstall bun

# npm
npm uninstall -g bun

Configuring Environment Variables

Adding to PATH

If the command is not found after installation, manually add PATH:

Linux/macOS (bash):

echo 'export BUN_INSTALL="$HOME/.bun"' >> ~/.bashrc
echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

macOS (zsh):

echo 'export BUN_INSTALL="$HOME/.bun"' >> ~/.zshrc
echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell:

# Add to user PATH
$env:BUN_INSTALL = "$env:USERPROFILE\.bun"
[Environment]::SetEnvironmentVariable("BUN_INSTALL", $env:BUN_INSTALL, "User")
[Environment]::SetEnvironmentVariable("PATH", "$env:BUN_INSTALL\bin;$env:PATH", "User")

Bun Configuration File

Bun uses bunfig.toml as the configuration file:

# bunfig.toml

# Package manager configuration
[install]
# Registry to use
registry = "https://registry.npmmirror.com"

# Don't save to package.json during install
save = false

# Dev dependency install location
dev = true

# Run configuration
[run]
# Silent mode
silent = false

# Test configuration
[test]
# Test timeout (milliseconds)
timeout = 5000

# Coverage report
coverage = true

Configuration File Location

Bun searches for configuration in the following order:

1. ./bunfig.toml (current directory)
2. $XDG_CONFIG_HOME/bun/bunfig.toml
3. ~/.bunfig.toml

Common Installation Issues

Issue 1: Insufficient Permissions

# Linux/macOS
curl -fsSL https://bun.sh/install | sudo bash

# Or change install directory permissions
sudo chown -R $USER ~/.bun

Issue 2: Network Issues

Use mirror acceleration:

# Use domestic mirror
curl -fsSL https://bun.sh/install | bash -s -- --mirror

Issue 3: Command Not Found

Ensure PATH is configured correctly:

# Check Bun installation location
which bun
# or
echo $BUN_INSTALL

Issue 4: Windows Execution Policy

# Temporarily allow script execution
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

IDE Support

VS Code

Install Bun extension for better development experience:

1. Open VS Code extension marketplace
2. Search for "Bun"
3. Install the official extension

Other IDEs

• WebStorm: Native Bun support
• Vim/Neovim: Use LSP configuration
• Sublime Text: Install related plugins

Summary

This chapter covered:

• ✅ Installing Bun on macOS, Linux, Windows
• ✅ Verifying installation and version management
• ✅ Configuring environment variables and config files
• ✅ Solving common installation issues

Next Steps

After installation, continue reading Quick Start to create your first Bun project.