Install and switch Bun versions

Manage Bun versions with OMG, use .bun-version for a project, verify GitHub release checksums, and separate runtime management from Bun package dependencies.

OMG maintainers · Updated · Source-reviewed guide

Pure Rust Bun installation from verified GitHub releases

OMG manages the Bun runtime using a compiled Rust pipeline in `src/runtimes/bun.rs`. Rather than relying on external install scripts or cURL pipelines, OMG communicates directly with GitHub Releases (`oven-sh/bun`), fetches platform release archives over HTTPS, and parses the release asset SHA-256 digest directly from the release metadata before allowing any disk writes.

The downloaded zip archive is unpacked into a staging directory using OMG’s pure-Rust zip decompressor (`extract_zip`) with single-directory component stripping. Upon successful extraction, OMG publishes the installation atomically to `~/.local/share/omg/versions/bun/<version>` and updates the `current` symlink.

Install and inspect Bun releases

omg use bun latest
omg use bun 1.2.4
omg list bun
omg which bun

OMG’s version resolver deterministically filters out release candidates and prereleases when resolving `latest` or partial version requests like `1.0`. Only stable production releases are selected unless an explicit prerelease tag is requested.

Published OMG releases target Linux x86_64 and Apple Silicon macOS. On Windows, run OMG inside WSL; Intel macOS and Linux ARM64 are not published release targets.

Project version pins and shell detection

When navigating between repositories, OMG’s directory hook (`src/hooks/mod.rs`) checks the nearest directory with a Bun pin first. Within one directory, it checks these sources in order:

  1. Project `.bun-version` file in the current working directory or any parent directory.

  2. Multi-runtime `.tool-versions` file (asdf and mise compatible).

  3. `package.json` engines (`engines.bun`) or Volta configuration (`volta.bun`).

Verify active Bun version at a new prompt

bun --version
omg which bun
which -a bun

Separating runtime management from package dependencies

OMG is responsible for fetching, validating, and activating the Bun binary on PATH. All project-level dependency operations—such as `bun install`, `bun add`, and managing `bun.lock` / `bun.lockb`—are handled natively by Bun itself.

If your project contains a `package.json` with scripts, you can execute them through Bun directly (`bun run build`) or through OMG’s task runner (`omg run build`). The published OMG task runner selects Bun when package.json names Bun in packageManager or when the project has a legacy bun.lockb. For a project using bun.lock, set packageManager to Bun to make runner selection explicit.

Install dependencies and run project tasks

bun install --frozen-lockfile
omg run build
omg run test

Diagnosing unexpected Bun executables

If your shell finds an unexpected Bun binary, check if an existing installation from `~/.bun/bin` or a system package manager precedes OMG in your PATH. Ensure the OMG shell hook is initialized in your shell configuration file.

Inspect shell PATH resolution

omg which bun
which -a bun
bun --version

Sources and verification

Commands and behavior are based on the references below. Source review is not a claim that every workflow has been executed on every supported platform.

Read as Markdown