Biome 02 🧹 Installation — Package manager setup & version pinning - KandZ

⏱️ Estimated read: 13 min | |

Biome is distributed as a single npm package, @biomejs/biome, and the installation is a one-line command with a flag that matters more than it looks. The -E flag—or --save-exact in its long form—pins the exact version in package.json instead of writing a caret range . The Biome documentation is explicit about why: “the -E flag pins the exact version in your package.json, so every contributor and your CI run the same version of Biome” . Without the flag, a caret range like ^2.6.2 allows a minor update to land silently, and a minor update in a formatter can change the output. The pinning is not a stylistic preference. It is the mechanism that keeps the local editor, the pre-commit hook, and the CI job formatting the same bytes.

Quick How-To Guides & Fast FixesNeed a quick fix or step-by-step solution? Browse our fast answers on HowTo.KandZ.me:

Operating Systems CLI →Dev Environment Languages →Web Network Tools →Security Accounts →Security Access Tech →Device Phone Basics →Social Messaging →Digital Files Media →

The installation surface is small, but the package manager differences and the editor integration are where the setup either works or produces a warning. The package manager installs the package and the optional native binary that matches the platform. The VS Code extension tries to load that binary from the project’s node_modules, and if the package manager has not installed the optional dependency, the extension shows a warning that it cannot resolve the library . The installation is the first step, and the version pinning and the editor resolution are the two details that determine whether the setup is stable.

Key point: Install Biome as a development dependency with the exact version pin: npm i -D -E @biomejs/biome or the equivalent for pnpm, yarn, bun, or deno. The -E flag writes the exact version to package.json, so every contributor and the CI run the same version. The VS Code extension loads the binary from the project’s node_modules, and the version pin is what keeps the extension and the CLI in sync.

Why the version pinning is the installation decision

The formatter output problem. A formatter’s output can change between minor versions. The change is not a bug; it is a deliberate improvement to the formatting rules. But a project that upgrades the formatter without noticing produces a diff that touches many files for a reason unrelated to the code change. The version pin is the mechanism that makes the upgrade a deliberate action: the version stays fixed until someone changes the package.json, and the change is reviewed like any other dependency update.

The editor and CLI sync problem. The VS Code extension tries to use the Biome binary from the project’s node_modules/@biomejs/biome . If the package.json has a range and the lockfile resolves to a different version than the one the CLI uses, the editor and the CLI can format the same file differently. The exact pin removes the ambiguity: the package.json names one version, the lockfile resolves that version, and the extension and the CLI both use it. The pinning is the mechanism that keeps the two surfaces consistent.

The CI reproducibility problem. A CI job installs the dependencies from the lockfile. If the package.json has a range and the lockfile is updated by a dependency bot, the CI can start using a new Biome version without any change to the repository’s code. The exact pin makes the CI’s Biome version explicit in the package.json, and the lockfile is the resolved form of that pin. The reproducibility is the reason the pinning is the default recommendation in the Biome documentation.

The trade-off. The exact pin means the project does not get the bug fixes and the improvements automatically. The upgrade is a manual step, and the step is the point. A formatter is a tool that changes the output, and the output change should be reviewed. The exact pin makes the upgrade a commit that a human makes, and the commit is the review. The automation is the trade-off against the control, and the formatter is the case where the control matters.

a. The package manager commands and the standalone installer

The installation command differs by the package manager, but the structure is the same: add the package as a development dependency with the exact pin. The npm form is npm i -D -E @biomejs/biome . The pnpm form is pnpm add -D -E @biomejs/biome . The yarn form is yarn add -D -E @biomejs/biome . The bun form is bun add -D -E @biomejs/biome . The deno form is deno add -D npm:@biomejs/biome .

# The npm installation with the exact pin
npm i -D -E @biomejs/biome

# The pnpm installation with the exact pin
pnpm add -D -E @biomejs/biome

# The yarn installation with the exact pin
yarn add -D -E @biomejs/biome

The -D flag is the development dependency, and the -E flag is the exact version. The combination is the standard installation, and the Biome quick start documents it as the three-step process: install, biome init, and biome check .

The standalone installer is the alternative for a project that does not use Node.js. The installer downloads the binary for the platform and adds it to the PATH . The installation command is curl -fsSL https://biomejs.dev/install | bash on macOS and Linux, and the PowerShell equivalent on Windows . The standalone binary does not need the package manager, and it does not need the package.json. The trade-off is the version pinning: the standalone installer installs the latest stable version unless a version is passed explicitly, and the upgrade is a separate command .

# The standalone installer (macOS and Linux)
curl -fsSL https://biomejs.dev/install | bash

# The standalone installer (Windows PowerShell)
irm https://biomejs.dev/install.ps1 | iex

The standalone installer is the choice for a project that uses Biome without a Node.js toolchain, or for a global installation that is not tied to a specific project. The package manager installation is the choice for a project that has a package.json, because the version is pinned and the CI can install it from the lockfile.

b. The VS Code extension and the binary resolution

The VS Code extension is the second half of the setup. The extension is installed from the Marketplace, and it registers itself as the formatter and the diagnostics provider for the supported file types . The extension tries to load the Biome binary from the project’s node_modules/@biomejs/biome, and the documentation recommends adding Biome as a project dependency so the extension and the npm scripts use the same version . The version pin is what makes the two surfaces consistent.

// .vscode/settings.json — the Biome as the default formatter
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit"
  }
}

The editor.defaultFormatter setting makes Biome the formatter for the supported file types, and the editor.formatOnSave setting applies the formatting on the save . The source.fixAll.biome action applies the safe fixes on the save, and the source.organizeImports.biome action sorts the imports . The settings are the editor-side configuration, and the biome.json is the project-side configuration.

The binary resolution warning is the common setup issue. The @biomejs/biome package specifies the optional dependencies for the platform and the architecture, and the extension may fail to resolve the binary if the package manager did not install the optional dependency . The fix is to install the specific binary package for the platform, or to install all the binary packages if the team works across the operating systems . The warning is the symptom, and the missing optional dependency is the cause.

# The binary packages for the cross-platform teams
npm i -D @biomejs/cli-darwin-arm64 @biomejs/cli-darwin-x64 @biomejs/cli-linux-arm64 @biomejs/cli-linux-x64 @biomejs/cli-win32-arm64 @biomejs/cli-win32-x64

The binary packages are the optional dependencies that the main package resolves for the current platform. The cross-platform installation is the workaround for the team that uses different operating systems, and the extension can then resolve the binary regardless of the platform .

Complete Example Session

# ============================================
# PART 1: THE PACKAGE MANAGER INSTALLATION
# ============================================

# The npm installation with the exact version pin.
npm i -D -E @biomejs/biome

# The -D flag is the dev dependency.
# The -E flag is the exact version.
# The package.json records the exact version, not the caret range.

# ============================================
# PART 2: THE VERSION PIN IN THE PACKAGE.JSON
# ============================================

# package.json
{
  "devDependencies": {
    "@biomejs/biome": "2.6.2"
  }
}

# The version is exact, not "^2.6.2".
# Every contributor and the CI run the same version.

# ============================================
# PART 3: THE INITIALIZATION
# ============================================

# npx biome init

# The command creates the biome.json.
# The generated file enables the formatter, the linter, and the assist actions.

# ============================================
# PART 4: THE CHECK COMMAND
# ============================================

# npx biome check

# The command runs the formatter, the linter, and the assist actions.
# The --write flag applies the safe fixes.

# ============================================
# PART 5: THE STANDALONE INSTALLER
# ============================================

# curl -fsSL https://biomejs.dev/install | bash

# The installer downloads the latest stable binary.
# The binary is added to the PATH.
# The installation is not tied to a package.json.

# ============================================
# PART 6: THE VS CODE EXTENSION
# ============================================

# The extension is installed from the Marketplace.
# The extension loads the binary from the node_modules.
# The exact pin keeps the extension and the CLI in sync.

# ============================================
# PART 7: THE SETTINGS.JSON
# ============================================

# .vscode/settings.json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit"
  }
}

# The editor uses Biome for the formatting and the safe fixes.

# ============================================
# PART 8: THE BINARY RESOLUTION WARNING
# ============================================

# The extension shows "cannot resolve library".
# The optional binary dependency is missing.
# The fix is to install the platform-specific binary package.

# ============================================
# PART 9: THE CROSS-PLATFORM BINARIES
# ============================================

# npm i -D @biomejs/cli-darwin-arm64 @biomejs/cli-linux-x64 @biomejs/cli-win32-x64

# The binary packages for the different platforms.
# The extension can resolve the binary on any platform.

# ============================================
# PART 10: THE CHECKLIST
# ============================================

# [ ] The @biomejs/biome is installed with the -E flag.
# [ ] The package.json records the exact version.
# [ ] The biome.json is created with the init command.
# [ ] The VS Code extension is installed.
# [ ] The editor.defaultFormatter is set to biomejs.biome.
# [ ] The editor.formatOnSave is enabled.
# [ ] The source.fixAll.biome is set in the codeActionsOnSave.
# [ ] The binary packages are installed for the cross-platform teams.

The ten parts covered the package manager installation, the version pin, the initialization, the check command, the standalone installer, the VS Code extension, the settings, the binary resolution warning, the cross-platform binaries, and the checklist. The through-line is that the exact pin is the mechanism that keeps the CLI, the editor, and the CI consistent.

Quick Reference

The installation commands

Package manager	Command
npm	`npm i -D -E @biomejs/biome`
pnpm	`pnpm add -D -E @biomejs/biome`
yarn	`yarn add -D -E @biomejs/biome`
bun	`bun add -D -E @biomejs/biome`
deno	`deno add -D npm:@biomejs/biome`
standalone (macOS/Linux)	`curl -fsSL https://biomejs.dev/install \| bash`
standalone (Windows)	`irm https://biomejs.dev/install.ps1 \| iex`

The flags

Flag	Purpose
`-D`	The development dependency
`-E`	The exact version pin
`--save-exact`	The long form of `-E`

The VS Code settings

Setting	Purpose
`editor.defaultFormatter`	`"biomejs.biome"`
`editor.formatOnSave`	`true`
`source.fixAll.biome`	The safe fixes on save
`source.organizeImports.biome`	The import sorting on save

The binary packages

Package	Platform
`@biomejs/cli-darwin-arm64`	macOS Apple silicon
`@biomejs/cli-darwin-x64`	macOS Intel
`@biomejs/cli-linux-arm64`	Linux ARM64
`@biomejs/cli-linux-x64`	Linux x64
`@biomejs/cli-win32-arm64`	Windows ARM64
`@biomejs/cli-win32-x64`	Windows x64

Best Practices

✅ Do This:

# Use the exact version pin
npm i -D -E @biomejs/biome                                        # ✅

// Set Biome as the default formatter
{ "editor.defaultFormatter": "biomejs.biome" }                    // ✅

# Install the binary packages for the cross-platform teams
npm i -D @biomejs/cli-darwin-arm64 @biomejs/cli-linux-x64        // ✅

❌ Don’t Do This:

# Use the caret range
npm i -D @biomejs/biome // the version can drift silently          // ❌

// Forget the format on save
{ "editor.formatOnSave": false }                                  // ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
The editor and the CLI format differently	The version range allows the drift	Use the `-E` flag
The extension shows “cannot resolve library”	The optional binary is missing	Install the platform binary
The format on save does nothing	The default formatter is not set	Set `editor.defaultFormatter`
The CI uses a different version	The lockfile is updated by a bot	Pin the exact version

Real-World Examples

1. The npm installation

npm i -D -E @biomejs/biome

2. The pnpm installation

pnpm add -D -E @biomejs/biome

3. The yarn installation

yarn add -D -E @biomejs/biome

4. The exact version in package.json

{ "@biomejs/biome": "2.6.2" }

5. The initialization

npx biome init

6. The check command

npx biome check

7. The VS Code formatter

{ "editor.defaultFormatter": "biomejs.biome" }

8. The format on save

{ "editor.formatOnSave": true }

9. The fix on save

{ "source.fixAll.biome": "explicit" }

10. The standalone installer

curl -fsSL https://biomejs.dev/install | bash

Visual

The Version Pin

┌──────────────────────────────────────────────────────────────┐
│  THE -E FLAG PINS THE EXACT VERSION                          │
│                                                              │
│  Without -E:                                                 │
│  ┌─────────────────────┐                                    │
│  │ "biome": "^2.6.2"   │  A minor update can land silently  │
│  └─────────────────────┘                                    │
│                                                              │
│  With -E:                                                    │
│  ┌─────────────────────┐                                    │
│  │ "biome": "2.6.2"    │  The version is fixed              │
│  └─────────────────────┘                                    │
│                                                              │
│  The pin keeps the CLI, the editor, and the CI consistent.   │
└──────────────────────────────────────────────────────────────┘

The Editor and CLI

┌──────────────────────────────────────────────────────────────┐
│  THE EXTENSION LOADS THE BINARY FROM node_modules            │
│                                                              │
│  package.json                                                │
│  ┌─────────────────────┐                                    │
│  │ @biomejs/biome      │  The exact version                 │
│  │ 2.6.2               │                                    │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ node_modules/       │  The binary                        │
│  │ @biomejs/biome      │                                    │
│  └──────────┬──────────┘                                    │
│             │                                                │
│      ┌──────┴──────┐                                         │
│      ▼             ▼                                         │
│  ┌────────┐   ┌────────┐                                    │
│  │ CLI    │   │ VS Code│                                    │
│  │        │   │ Ext    │                                    │
│  └────────┘   └────────┘                                    │
│                                                              │
│  The exact pin keeps the two surfaces in sync.              │
└──────────────────────────────────────────────────────────────┘

The Binary Resolution

┌──────────────────────────────────────────────────────────────┐
│  THE PLATFORM BINARY                                         │
│                                                              │
│  @biomejs/biome                                              │
│  ┌─────────────────────┐                                    │
│  │ The main package    │  Resolves the optional binary      │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ @biomejs/cli-       │  The platform-specific binary      │
│  │ darwin-arm64        │                                    │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The extension loads │  The binary from node_modules      │
│  │ the binary          │                                    │
│  └─────────────────────┘                                    │
│                                                              │
│  The missing optional dependency causes the warning.        │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
Package	`@biomejs/biome`
Exact pin flag	`-E` (npm, pnpm, yarn, bun)
Standalone installer	`curl -fsSL https://biomejs.dev/install \| bash`
Initialization	`npx biome init`
Check command	`npx biome check`
VS Code formatter	`"editor.defaultFormatter": "biomejs.biome"`
Binary resolution	The extension loads from `node_modules`

Key takeaways:

The -E flag is the version pin. It writes the exact version to package.json instead of the caret range, so every contributor and the CI run the same version . The pin is the mechanism that keeps the CLI, the editor, and the CI consistent.
The package manager installation is the standard for a project with a package.json. The npm, pnpm, yarn, bun, and deno commands all use the -D -E flags, and the biome init and biome check are the next two steps .
The standalone installer is the alternative for a project without Node.js. It downloads the platform binary and adds it to the PATH, and it is the choice for a global installation that is not tied to a specific project .
The VS Code extension loads the binary from the project’s node_modules. The exact pin keeps the extension and the CLI in sync, and the missing optional dependency is the cause of the “cannot resolve library” warning .
The binary packages are the cross-platform fix. The @biomejs/cli-* packages are the platform-specific binaries, and installing them explicitly resolves the warning for a team that works across the operating systems .

Remember: The Biome installation is a one-line command with the -E flag, and the flag is the decision that matters. The exact pin keeps the version fixed, the biome init creates the configuration, and the biome check runs the formatter, the linter, and the assist actions in one pass. The VS Code extension is the editor-side setup, and the binary resolution is the detail that either works or produces a warning. The installation is the first step, and the pinning is the mechanism that makes the rest stable.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!