Manage Multiple Bun Versions Without Tools

Previously, we might have explored how to manually manage Go or Node.js versions without relying on external tools. Now, let’s apply the same principles to Bun.

Whether you’re testing out the newest JavaScript runtime features, ensuring backward compatibility across minor releases, or maintaining legacy services, managing multiple Bun versions can save you time and prevent unexpected issues. While version managers are common, you may prefer the transparency and control of a manual setup.

Step 1: Download and Install Multiple Bun Versions

Start by downloading the specific Bun release binaries directly from the official Bun GitHub Releases page scroll down to the “Assets” and download your specific OS zip file, for example the bun-darwin-aarch64.zip for Apple Silicon. By default, these zip archives will land in your Downloads folder.

Extract the archives. You’ll notice the folder contains the bun binary directly. Rename each version-specific folder, and for consistency, install each version in its own directory inside /usr/local.

For example, compiling for your local Apple Silicon hardware:

# Move the extracted Bun 1.0 installation to its own directory
sudo mv ~/Downloads/bun-darwin-aarch64 /usr/local/bun1.0

Repeat the process for other versions:

• Bun 1.1 → /usr/local/bun1.1
• Bun 1.3 → /usr/local/bun1.3
• ….

By isolating each version, you ensure zero overlap between your runtime environments.

Step 2: Set Up Aliases for Quick Switching

Create aliases in your shell configuration to switch between Bun versions easily.

Open your shell config file:

nano ~/.zshrc # For zsh
# or
nano ~/.bash_profile # For bash

Add the following lines. Note that unlike Node.js, Bun’s binary isn’t nested inside a bin folder within the release archive, so we point the path directly to the folder:

# Aliases for switching Bun versions
alias bun1.0='export PATH=/usr/local/bun1.0:$PATH'
alias bun1.1='export PATH=/usr/local/bun1.1:$PATH'
alias bun1.3='export PATH=/usr/local/bun1.3:$PATH'

# Set the default Bun version
bun1.3

Save the file and reload your shell configuration:

source ~/.zshrc # For zsh
source ~/.bash_profile  # For bash

Note on macOS Security: Since you are downloading binaries directly, macOS might block execution with a warning: “Apple could not verify ‘bun’ is free of malware that may harm your Mac or compromise your privacy”. To bypass this quarantine flag, run:

sudo xattr -rd com.apple.quarantine /usr/local/bun1.0
sudo xattr -rd com.apple.quarantine /usr/local/bun1.1
sudo xattr -rd com.apple.quarantine /usr/local/bun1.3

Step 3: Verify

You can now switch between versions with simple alias commands:

# Check the default version
$ bun -v
# Output: 1.1.x

# Switch to Bun 1.0
$ bun1.0

$ bun -v
# Output: 1.0.x

Each alias prepends the appropriate Bun directory to your $PATH, ensuring that your shell uses the correct bun and bunx executables.

Conclusion

Manually managing Bun versions gives you a clean, dependency-free way to work across multiple environments. This method is especially helpful for:

• Testing performance improvements across runtime updates.
• Running older projects without updating their lockfiles.
• Avoiding third-party tools in restricted or minimal environments.

You now have full control of your Bun toolchain, no version managers needed.