# 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.

Canonical: https://getomg.xyz/runtimes/bun/
Updated: 2026-09-22
Author: OMG maintainers

## 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

```sh
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

```sh
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

```sh
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

```sh
omg which bun
which -a bun
bun --version
```

## Sources and verification

Source-reviewed guidance; not a claim of execution on every supported platform.

- [OMG Bun runtime implementation (src/runtimes/bun.rs)](https://getomg.xyz/docs/runtimes/)

- [OMG shell hook resolution (src/hooks/mod.rs)](https://getomg.xyz/docs/architecture/)

- [Bun official GitHub releases](https://github.com/oven-sh/bun/releases)

- [Bun lockfile documentation](https://github.com/oven-sh/bun/blob/main/docs/pm/lockfile.mdx)

## Related pages

- https://getomg.xyz/runtimes/node/

- https://getomg.xyz/guides/node-npm-pnpm/

- https://getomg.xyz/compare/omg-vs-mise/