#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:

#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.