How to safely upgrade Bun and roll back to a previous version

Upgrading and Reverting Bun

The safest way to manage Bun versions is through the built-in upgrade command. Because Bun is distributed as a single binary, rolling back is a matter of instructing the runtime to replace itself with a specific previous version.

Step-by-Step Upgrade Process

1. Verify Current Version: Before upgrading, record your current stable version to ensure you have a known recovery point.

   bun --version

2. Execute Upgrade: Run the upgrade command to fetch the latest stable release.

   bun upgrade

3. Verify Update: Confirm the binary has been replaced and is functioning.

   bun --version

Rollback Strategy

If the new version introduces regressions or failures, you can roll back by specifying the exact version number you recorded in step one.

1. Target Previous Version: Use the --version flag to downgrade.

   bun upgrade --version 1.0.0

   (Replace 1.0.0 with your specific previous version)
2. Confirm Restoration: Verify that the runtime has reverted.

   bun --version

Technical Considerations and Assumptions

This approach assumes Bun was installed via the official curl script (typically residing in ~/.bun/bin). If you are using a version manager or a system-level package manager, these commands may not behave as expected.

Manual Backup (High-Safety Method)

For production environments where downtime must be minimized, manually backing up the binary is recommended before any upgrade:

• Backup: Copy the current binary to a backup file (e.g., cp ~/.bun/bin/bun ~/.bun/bin/bun.bak).
• Manual Restore: If the upgrade fails and the upgrade --version command is unavailable, move the backup back into place: mv ~/.bun/bin/bun.bak ~/.bun/bin/bun.

Diagnostic Detail: Are you running Bun via the official install script, or are you using a third-party manager like asdf or homebrew? The rollback commands differ for external managers.