bun upgrade: Update Bun Itself

bun upgrade replaces the installed Bun binary with the latest stable release, or the canary build with --canary.

bun upgrade keeps the Bun runtime current on a developer machine. In CI you generally want the opposite: a pinned version, so upgrade is a local command more than a pipeline one.

What it does

bun upgrade downloads and installs the newest Bun release in place, replacing the current binary. With --canary it installs the latest canary (nightly) build instead of stable. bun --version reports the active version.

Common usage

Terminal

bun upgrade
bun upgrade --canary                # latest nightly build
bun --version                       # check the active version
bun --revision                      # exact build revision

Options

Flag	What it does
--canary	Install the latest canary (nightly) build
--stable	Force the latest stable release
bun --version	Print the installed version
bun --revision	Print the exact build revision

In CI

Do not run bun upgrade in CI; an unpinned upgrade makes builds non-reproducible and can introduce regressions mid-pipeline. Pin the Bun version with oven-sh/setup-bun (bun-version: 1.1.x) so every run uses the same toolchain. Bump the pin deliberately in a PR and let tests vet it.

Common errors in CI

If a build suddenly breaks after a runner image refresh, an unpinned Bun likely upgraded; pin bun-version in setup-bun. "error: Failed to download" during upgrade is a transient network/GitHub issue. A canary build that crashes is expected risk; use --stable for anything but testing the nightly.