Bun 02 ⚡ Installing Bun and Managing Global Versions

Bun is distributed as a single, dependency-free executable. There is no runtime environment to configure, no virtual machine to install, and no package manager to bootstrap. The installation is one command, and the resulting binary contains everything: the runtime, the package manager, the bundler, and the test runner. Managing versions is equally direct: bun upgrade replaces the binary in place, and installing a specific version means re-running the install script with a version tag. For projects that need isolated versions, external tools like mise or bunenv provide the switching layer that Bun itself does not include.

Key point: bun upgrade is the built-in version manager. It downloads and replaces the current binary with the latest stable release. For switching between multiple versions on the same machine, use mise or bunenv—Bun does not bundle a version manager of its own.

---

Why Bun’s installation model is different

The single binary problem. Node.js requires a platform-specific installer that places the binary and the npm CLI in a system directory, along with a global node_modules tree. Bun ships as one file. The install script downloads the correct binary for the platform, places it in ~/.bun/bin, and updates the shell configuration to include that directory in PATH . There is no system-wide package database to corrupt, no global directory to clean up, and no version conflict between Bun and a system package manager.

The upgrade problem. Because Bun is a single binary, upgrading is a matter of replacing that binary. The bun upgrade command downloads the latest release and overwrites the existing executable . There is no package manager transaction, no dependency resolution, and no lockfile. If the upgrade fails, the old binary is still present until the replacement succeeds.

The version isolation problem. Bun does not ship with a version manager. A project that requires Bun 1.2 and another that requires Bun 1.4 cannot both use the same global binary. The built-in bun upgrade always targets the latest stable release (or the latest canary, if the current binary is a canary) . For isolated environments, tools like mise and bunenv provide the per-project switching that Bun’s built-in tooling lacks.

The package manager conflict problem. If Bun was installed via Homebrew or Scoop, bun upgrade should not be used. The package manager owns the binary, and bun upgrade would replace it outside the package manager’s knowledge. The correct upgrade path is brew upgrade bun or scoop update bun .

The trade-off. The single-binary model is simple and fast, but it places the responsibility for version isolation on external tools. For a single global version, bun upgrade is sufficient. For multiple projects with conflicting requirements, a version manager is mandatory.

---

a. Installing Bun

The official install script supports macOS, Linux, and Windows. On Linux, the unzip package must be installed first, and the kernel must be 5.6 or newer (with graceful degradation on older kernels) .

# macOS and Linux
curl -fsSL https://bun.com/install | bash

# Windows (PowerShell)
irm https://bun.com/install.ps1 | iex

After installation, the binary is placed in ~/.bun/bin. If the shell does not automatically source the updated PATH, the directory must be added manually .

# Add to ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

The installation is verified with two commands. bun --version reports the semantic version, and bun --revision reports the exact commit hash of the binary .

bun --version
# Output: 1.4.1

bun --revision
# Output: 1.4.1+b7982ac13189

Alternative installation methods exist for environments where the install script is blocked or a system package manager is preferred. npm install -g bun installs the binary through npm, which is useful in CI containers that already have Node.js. Homebrew (brew install oven-sh/bun/bun) and Scoop (scoop install bun) are available for macOS and Windows respectively . Docker images are published for Linux x64 and arm64 under oven/bun .

---

b. Upgrading Bun

The bun upgrade command downloads and installs the latest stable version. If the currently installed binary is a canary build, the command upgrades to the latest canary instead .

# Upgrade to latest stable (or canary if on canary)
bun upgrade

# Upgrade to latest canary (development build)
bun upgrade --canary

# Return to stable from canary
bun upgrade --stable

Canary builds are published from the main branch after CI passes. They are useful for testing new features or verifying bug fixes before a release, but they are not recommended for production because they may contain breaking changes .

If Bun was installed through a package manager, that package manager must be used for upgrades. Using bun upgrade alongside Homebrew or Scoop creates a conflict between two systems that both believe they own the binary .

# Homebrew
brew upgrade bun

# Scoop
scoop update bun

---

c. Managing versions with external tools

Bun’s built-in upgrade command always targets a single global version. For projects that require different versions, two external tools provide isolation.

The mise tool (formerly rtx) is a general-purpose version manager that supports Bun alongside Node.js, Python, and other runtimes. A project declares its Bun version in mise.toml, and mise selects the correct binary when commands run in that directory .

# Install Bun globally with mise
mise use -g bun@latest

# Pin a project to a specific version
mise use bun@1.3.3

# Upgrade within mise
mise upgrade bun

The bunenv tool is a Python-based environment manager modeled after pyenv. It creates isolated environments that contain a specific Bun version and can be activated per shell session .

# Install bunenv
pip install bunenv

# Create an environment with a specific version
bunenv myenv --bun=1.3.3

# Activate it
source myenv/bin/activate

# Verify
bun --version
# Output: 1.3.3

Installing a specific version directly, without a version manager, is also possible by passing a version tag to the install script. This replaces the global binary, so it is appropriate only when the entire machine should use that version .

# macOS and Linux: install a specific version
curl -fsSL https://bun.com/install | bash -s "bun-v1.3.3"

# Windows: install a specific version
iex "& {$(irm https://bun.com/install.ps1)} -Version 1.3.3"

---

Complete Example Session

# ============================================
# PART 1: INSTALL BUN
# ============================================

curl -fsSL https://bun.com/install | bash
# Binary placed in ~/.bun/bin/bun

# ============================================
# PART 2: VERIFY PATH
# ============================================

bun --version
# If "command not found":
# Add ~/.bun/bin to PATH and reload shell.

# ============================================
# PART 3: CHECK REVISION
# ============================================

bun --revision
# Output: 1.4.1+b7982ac13189

# ============================================
# PART 4: UPGRADE TO LATEST STABLE
# ============================================

bun upgrade
# Downloads and replaces the binary.

# ============================================
# PART 5: TRY A CANARY BUILD
# ============================================

bun upgrade --canary
# Installs the latest canary build.

# ============================================
# PART 6: RETURN TO STABLE
# ============================================

bun upgrade --stable
# Restores the latest stable release.

# ============================================
# PART 7: INSTALL A SPECIFIC VERSION
# ============================================

curl -fsSL https://bun.com/install | bash -s "bun-v1.3.3"
# Replaces the global binary with 1.3.3.

# ============================================
# PART 8: ISOLATE WITH MISE
# ============================================

mise use bun@1.3.3
# Project-local version pinned in mise.toml.

# ============================================
# PART 9: ISOLATE WITH BUNENV
# ============================================

bunenv .venv --bun=1.3.3
source .venv/bin/activate
bun --version
# Output: 1.3.3

The nine parts trace installation, verification, upgrading, canary testing, returning to stable, pinning a specific version globally, and isolating versions with mise and bunenv.

---

Quick Reference

Installation Commands

Platform	Command
macOS / Linux	curl -fsSL https://bun.com/install | bash
Windows	irm https://bun.com/install.ps1 | iex
npm	npm install -g bun
Homebrew	brew install oven-sh/bun/bun
Scoop	scoop install bun

Upgrade Commands

Command	Effect
bun upgrade	Latest stable (or canary if on canary)
bun upgrade --canary	Latest canary build
bun upgrade --stable	Return to stable from canary
brew upgrade bun	Homebrew-managed upgrade
scoop update bun	Scoop-managed upgrade

Specific Version Installation

Platform	Command
macOS / Linux	curl -fsSL https://bun.com/install | bash -s "bun-v1.3.3"
Windows	iex "& {$(irm https://bun.com/install.ps1)} -Version 1.3.3"

Version Managers

Tool	Command
mise	mise use bun@1.3.3
bunenv	bunenv .venv --bun=1.3.3

---

Best Practices

✅ Do This:

bun --revision
<!-- Check the exact commit, not just the version --> # ✅

brew upgrade bun
<!-- Use the package manager that installed Bun -->   # ✅

mise use bun@1.3.3
<!-- Pin project versions for reproducibility -->    # ✅

❌ Don’t Do This:

bun upgrade
# When Bun was installed via Homebrew or Scoop
<!-- Causes conflict between two managers -->        # ❌

# Use bun upgrade for multi-version projects
<!-- It only manages one global binary -->           # ❌

# Forget to add ~/.bun/bin to PATH
<!-- Binary exists but is unreachable -->            # ❌

---

Common Pitfalls

Pitfall	Why It Happens	Fix
bun: command not found	~/.bun/bin not in PATH	Add to shell config and reload
Upgrade fails	Installed via Homebrew/Scoop	Use brew upgrade or scoop update
Canary build in production	bun upgrade --canary ran	bun upgrade --stable to return
Multiple projects conflict	Single global binary	Use mise or bunenv
Linux install fails	unzip not installed	sudo apt install unzip

---

Real-World Examples

1. Standard Install

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

2. Verify Installation

bun --version && bun --revision

3. Upgrade Stable

bun upgrade

4. Install Canary

bun upgrade --canary

5. Return to Stable

bun upgrade --stable

6. Homebrew Upgrade

brew upgrade bun

7. Specific Version

curl -fsSL https://bun.com/install | bash -s "bun-v1.3.3"

8. Pin with mise

mise use bun@1.3.3

9. Isolate with bunenv

bunenv .venv --bun=1.3.3

10. Add to PATH

export PATH="$HOME/.bun/bin:$PATH"

---

Visual

Installation and PATH Flow

┌──────────────────────────────────────────────┐
│  curl https://bun.com/install | bash         │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Binary written to ~/.bun/bin/bun            │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Shell PATH includes ~/.bun/bin?             │
│  ├─ YES → bun --version works                │
│  └─ NO  → command not found                  │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Add to ~/.bashrc or ~/.zshrc:               │
│  export PATH="$HOME/.bun/bin:$PATH"          │
└──────────────────────────────────────────────┘

Version Management Paths

┌──────────────────────────────────────────────┐
│  Single global version?                      │
└──────────┬───────────────────────┬───────────┘
           │ YES                   │ NO
           ▼                       ▼
┌──────────────────────┐  ┌──────────────────────┐
│  bun upgrade         │  │  mise use bun@...    │
│  (or brew/scoop)     │  │  or bunenv           │
└──────────────────────┘  └──────────────────────┘

The built-in upgrade handles one binary. Multi-version isolation requires an external tool.

---

Summary

Item	Value
Binary location	~/.bun/bin/bun
Version check	bun --version
Revision check	bun --revision
Upgrade	bun upgrade
Canary upgrade	bun upgrade --canary
Stable return	bun upgrade --stable
Specific version	Install script with tag
Version isolation	mise or bunenv
Package manager upgrade	brew upgrade bun / scoop update bun

Key takeaways:

• Bun is a single binary with no dependencies. The install script places it in ~/.bun/bin, and the shell PATH must include that directory .
• bun upgrade manages the global binary. It replaces the existing executable with the latest stable or canary build. If Bun was installed via Homebrew or Scoop, use the package manager’s upgrade command instead .
• A specific version can be installed globally. Pass a version tag to the install script. This replaces the global binary, so it is appropriate only when the entire machine should use that version .
• Version isolation requires an external tool. Bun does not include a version manager. mise and bunenv provide per-project switching for projects with conflicting version requirements .
• bun --revision reports the exact commit. The semantic version alone does not identify the specific build. The revision includes the commit hash .

Remember: Bun’s installation model is the binary. There is no runtime environment, no global package tree, and no version database. bun upgrade replaces the binary; the install script can pin a specific version; and external tools handle isolation when one global version is not enough. The simplicity is the point—and the limitation.

---

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!