BVM — Bun Version Manager

The Native, Zero-Dependency Version Manager for Bun

Official Website & Documentation »
中文网站 »

🇨🇳 中文文档 · Report Bug · Request Feature

---

⚡ Quick Install

BVM uses a smart installation script that automatically detects your OS and network environment (selecting the fastest registry for China/Global users).

Method 1: Shell Script (Recommended - macOS / Linux)

curl -fsSL https://bvm-core.pages.dev/install | bash

Method 2: PowerShell (Recommended - Windows)

irm https://bvm-core.pages.dev/install | iex

Method 3: NPM (Optional)

npm install -g bvm-core@latest --foreground-scripts

---

Key Features

• 🚀 Zero Latency: Shim-based design ensures ~0ms shell startup overhead.
• 🛡️ Bunker Architecture: BVM manages its own isolated Bun runtime, ensuring stability even if your system Bun is broken or missing.
• 🛡️ Atomic Isolation: Each Bun version has its own global package directory. No more conflicts.
• 🌏 Smart Mirroring & Auto-Config: Automatically selects the fastest registry for downloads AND auto-configures bunfig.toml for instant, "no-magic" bun install speeds.
• 📦 Zero Dependency: BVM bootstraps itself. No pre-requisites required (it can reuse your system Bun or download its own).

---

Usage

Basic Commands

• bvm install latest: Install the latest stable version of Bun.
• bvm install 1.1.0: Install a specific version.
• bvm use 1.1.0: Switch the active Bun version immediately.
• bvm default 1.1.0: Set a global default version for new shell sessions.
• bvm ls: List all locally installed versions.
• bvm ls-remote: List all available versions from the registry.
• bvm uninstall 1.1.0: Remove a specific version.
• bvm upgrade: Upgrade BVM itself to the latest version.

Running Commands

You can run a command with a specific Bun version without switching your global environment:

bvm run 1.0.30 index.ts

Aliases

Create custom names for specific versions:

bvm alias prod 1.1.0
bvm use prod

Configuration (.bvmrc)

BVM supports automatic version switching via .bvmrc files. Create a file named .bvmrc in your project root:

echo "1.1.0" > .bvmrc

---

Troubleshooting

• Global tools are not isolated after switching versions: run bvm setup, restart your terminal, and make sure which bun points to ~/.bvm/shims/bun (macOS/Linux). On Windows, use where.exe bun and ensure ...\\.bvm\\shims\\bun.cmd is first.
• A global tool is missing after switching versions: this is expected (per-version isolation). Reinstall it under the active Bun version.

---

Design Philosophy

ArchSense (Self-Bootstrapping)

BVM does not ship with heavy pre-compiled binaries. Instead, it uses Bun to manage Bun. The installer downloads a minimal Bun runtime to serve as BVM's execution engine, ensuring the manager itself is always running on the most optimized environment.

Atomic Isolation

Unlike managers that only switch the PATH, BVM performs Filesystem-level Locking. It dynamically injects a unique BUN_INSTALL path for every version, ensuring that global packages installed in one version never conflict with another.

---

License

MIT © EricLLLLLL