Install and Package Commands

Relevant source files

• src/bun.js/bindings/JSEnvironmentVariableMap.cpp
• src/bun.zig
• src/cli/bunx_command.zig
• src/cli/create_command.zig
• src/cli/init_command.zig
• src/cli/install_completions_command.zig
• src/cli/run_command.zig
• src/cli/upgrade_command.zig
• src/env_loader.zig
• src/install/bin.zig
• src/install/dependency.zig
• src/install/extract_tarball.zig
• src/install/install.zig
• src/install/lockfile.zig
• src/install/migration.zig
• src/install/npm.zig
• src/install/repository.zig
• src/install/resolution.zig
• src/install/windows-shim/BinLinkingShim.zig
• src/install/windows-shim/bun_shim_impl.zig
• test/cli/init/init.test.ts
• test/cli/install/__snapshots__/bun-install.test.ts.snap
• test/cli/install/__snapshots__/semver.test.ts.snap
• test/cli/install/bad-workspace.test.ts
• test/cli/install/bun-add.test.ts
• test/cli/install/bun-create.test.ts
• test/cli/install/bun-install-pathname-trailing-slash.test.ts
• test/cli/install/bun-install-retry.test.ts
• test/cli/install/bun-install.test.ts
• test/cli/install/bun-link.test.ts
• test/cli/install/bun-publish.test.ts
• test/cli/install/bun-remove.test.ts
• test/cli/install/bun-run.test.ts
• test/cli/install/bun-update.test.ts
• test/cli/install/bunx.test.ts
• test/cli/install/dummy.registry.ts
• test/cli/install/semver-fixture.js
• test/cli/install/semver.test.ts
• test/cli/run/env.test.ts
• test/cli/run/garbage-env.c
• test/cli/run/garbage-env.test.ts
• test/harness.ts
• test/regression/issue/02977.test.ts
• test/regression/issue/08040.test.ts

This page documents the command-line interface for Bun's package management commands: bun install, bun add, bun remove, bun update, and bun link. These commands provide the user-facing interface to Bun's package manager functionality.

For information about the underlying package manager implementation, dependency resolution, and lockfile format, see Package Manager. For details on CLI architecture and command routing, see CLI Architecture and Command Dispatch.

Command Overview

Bun provides the following package management and initialization commands:

Command	Purpose	Aliases
bun install	Install all dependencies from package.json	bun i
bun add <packages...>	Add dependencies to package.json	bun a
bun remove <packages...>	Remove dependencies from package.json	bun rm
bun update <packages...>	Update dependencies to latest versions	bun up
bun link	Register or link local packages	-
bun unlink	Unregister linked packages	-
bunx <package>	Execute package binaries (ephemeral install)	bun x
bun create <template> [dest]	Scaffold new projects from templates	-
bun init	Initialize a new project interactively	-

All commands support common options like --registry, --cwd, and environment-specific flags.

Sources: test/cli/install/bun-install.test.ts1-850 test/cli/install/bun-add.test.ts1-900 test/cli/install/bun-remove.test.ts1-200 test/cli/install/bun-update.test.ts1-250 test/cli/install/bun-link.test.ts1-300 src/cli/bunx_command.zig1-128 src/cli/create_command.zig1-190 src/cli/init_command.zig1-143

Command Dispatch Flow

Sources: src/install/lockfile.zig218-370 src/install/migration.zig1-200 test/cli/install/bun-install.test.ts73-245

bun install

The bun install command reads package.json, resolves dependencies, downloads packages from registries, and installs them into node_modules.

Basic Usage

Command Flow

Sources: src/install/lockfile.zig218-400 src/install/extract_tarball.zig108-200 src/install/migration.zig3-100

CLI Options

Option	Type	Description	Default
--registry	URL	Override default npm registry	https://registry.npmjs.org
--network-concurrency	Number (0-65535)	Limit concurrent network requests	System default
--cwd	Path	Working directory for install	Current directory
--frozen-lockfile	Boolean	Fail if lockfile needs update	false
--production	Boolean	Install only production dependencies	false
--dry-run	Boolean	Simulate install without changes	false
--force	Boolean	Force reinstall all packages	false
--cache	Boolean	Enable/disable cache	true

The --network-concurrency option must be a number between 0 and 65535. Values outside this range will cause an error:

Expected --network-concurrency to be a number between 0 and 65535

Sources: test/cli/install/bun-install.test.ts74-104 test/cli/install/bun-install.test.ts400-460

Lockfile Migration

When no bun.lock or bun.lockb exists, Bun automatically detects and migrates from other package managers:

Sources: src/install/migration.zig3-100 test/cli/install/migration/migrate.test.ts10-50

Error Handling

Common errors during bun install:

1. Missing Package: Returns 404 error with helpful message
2. Connection Errors: Reports ConnectionRefused or ConnectionClosed
3. Invalid package.json: Reports parse errors with line numbers
4. Integrity Check Failed: Validates tarball checksums match package metadata
5. NPM Lockfile Version Mismatch: Prompts upgrade to lockfileVersion 2 or 3

Sources: test/cli/install/bun-install.test.ts341-398 test/cli/install/bun-install.test.ts612-646

bun add

The bun add command adds one or more dependencies to package.json and installs them.

Basic Usage

Dependency Types

Sources: test/cli/install/bun-add.test.ts43-93

File and Path Dependencies

bun add supports various path formats:

All of these result in a file: dependency in package.json:

Sources: test/cli/install/bun-add.test.ts276-324

Special Options

--only-missing

The --only-missing flag skips installation if the package is already installed:

Sources: test/cli/install/bun-add.test.ts128-200

--analyze

The --analyze flag scans source files to detect dependencies:

This analyzes the import graph starting from the specified file and adds any missing npm packages to package.json.

Sources: test/cli/install/bun-add.test.ts202-274

Add Command Implementation

Sources: src/install/dependency.zig282-800 test/cli/install/bun-add.test.ts1-900

bun remove

The bun remove command removes dependencies from package.json and the installed packages from node_modules.

Basic Usage

Remove Flow

Sources: test/cli/install/bun-remove.test.ts22-90 src/install/lockfile.zig555-650

Lockfile Cleaning

When removing packages, Bun calls Lockfile.clean() to remove unused dependencies from the lockfile. This process:

1. Creates a new lockfile with only reachable packages
2. Clones packages that are still referenced
3. Remaps package IDs in the dependency tree
4. Updates the preinstall_state array

Sources: src/install/lockfile.zig555-773

bun update

The bun update command updates dependencies to their latest compatible versions according to semver ranges in package.json.

Basic Usage

Update Flow

Sources: test/cli/install/bun-update.test.ts30-150 src/install/lockfile.zig467-554

Version Update Logic

The update logic in Lockfile.preprocessUpdateRequests() determines new version strings:

1. If --exact flag: Use exact version "1.2.3"
2. Otherwise: Use caret range "^1.2.3"
3. Handles aliases and special dependency types
4. Updates Dependency.version fields in lockfile

Sources: src/install/lockfile.zig467-554

bun link

The bun link command creates symlinks between local packages for development.

Basic Usage

Link Workflow

Sources: test/cli/install/bun-link.test.ts36-200

Workspace Package Linking

For workspace packages, bun link can link packages within a monorepo:

Workspace packages are identified by Resolution.Tag.workspace in the lockfile.

Sources: test/cli/install/bun-link.test.ts36-100 src/install/resolution.zig42-80

bunx

The bunx command (alias: bun x) executes package binaries without permanently installing them. This is similar to npx but uses Bun's package manager for faster execution.

Basic Usage

Command Flow

Diagram: bunx execution pipeline

Sources: src/cli/bunx_command.zig1-128 src/cli/bunx_command.zig32-98

CLI Options

Option	Type	Description	Default
--package / -p	String	Package to install (when binary name differs)	Inferred from command
--bun / -b	Boolean	Run using bun runtime	false
--silent	Boolean	Suppress installation output	false
--verbose	Boolean	Show detailed installation logs	false
--no-install	Boolean	Error if package not cached	false

The --package flag allows running a binary from a package with a different name:

Sources: src/cli/bunx_command.zig32-98

Cache Management

Diagram: bunx cache structure

The temporary installation directory format is /tmp/bunx-{uid}-{pkg} on Unix systems, where {uid} is the user ID and {pkg} is a hash of the package name and version.

Sources: src/cli/bunx_command.zig128-250 test/cli/install/bunx.test.ts1-200

Binary Resolution

When --package is not specified, bunx infers the package name from the binary name:

The binary resolution follows this order:

1. Check bin field in package.json
2. Look for executable in node_modules/.bin/
3. Search package root for matching executable

Sources: src/cli/bunx_command.zig99-127 src/cli/run_command.zig387-415

Error Handling

Common bunx errors:

1. Package not found with --no-install:

   error: Package 'some-package' not found in cache
   

2. Binary not found in package:

   error: Binary 'some-bin' not found in package 'some-package'
   

3. Invalid package name:

   error: --package requires a non-empty package name
   

Sources: src/cli/bunx_command.zig62-90 test/cli/install/bunx.test.ts100-150

bun create

The bun create command scaffolds new projects from templates. Templates can be official Bun examples, npm packages, GitHub repositories, or local directories.

Basic Usage

Command Flow

Diagram: bun create project scaffolding pipeline

Sources: src/cli/create_command.zig142-231 src/cli/create_command.zig1-52

CLI Options

Option	Type	Description	Default
--force	Boolean	Overwrite existing files	false
--no-install	Boolean	Skip bun install	false
--no-git	Boolean	Skip git init	false
--no-package-json	Boolean	Skip package.json transforms	false
--verbose	Boolean	Show detailed logs	false
--open	Boolean	Open in browser after creation	false

Sources: src/cli/create_command.zig142-189

File Filtering

The create command skips certain directories and files to avoid copying unnecessary data:

Skipped directories (defined in skip_dirs):

• node_modules
• .git

Skipped files (defined in skip_files):

• package-lock.json
• yarn.lock
• pnpm-lock.yaml

Never conflict files (defined in never_conflict):

• README.md
• .gitignore
• .git/

These files are always copied, even if they exist at the destination.

Sources: src/cli/create_command.zig12-28

Package.json Transformations

Unless --no-package-json is specified, bun create modifies the template's package.json:

Diagram: package.json transformation pipeline

The script replacement logic (defined in replacePackageManagerRun):

• npm run → bun run
• yarn run → bun run
• pnpm run → bun run
• npx → bun x
• pnpm dlx → bun x

Sources: src/cli/create_command.zig31-51 src/cli/run_command.zig86-204

Official Templates

Bun provides official example templates in the examples/ directory. These can be accessed using shorthand names:

The template resolution checks for official examples first before attempting to download from npm or git.

Sources: src/cli/create_command.zig194-231 test/cli/install/bun-create.test.ts1-100

Git Integration

By default, bun create initializes a git repository in the created project:

1. Runs git init in project directory
2. Creates initial commit with template files
3. Respects existing .gitignore from template

This can be skipped with --no-git.

Sources: src/cli/create_command.zig142-189

bun init

The bun init command initializes a new Bun project interactively, creating package.json, tsconfig.json, and optionally a .gitignore.

Basic Usage

Initialization Flow

Diagram: bun init interactive setup

Sources: src/cli/init_command.zig1-143 src/cli/init_command.zig2-40

Interactive Prompts

The prompt() function reads user input with default values:

package name: (my-project) 

Users can press Enter to accept defaults or type new values. The prompt system:

• Disables virtual terminal input on Windows to fix backspace behavior
• Trims whitespace from input
• Returns default if input is empty

Sources: src/cli/init_command.zig2-40

Package Type Selection

Diagram: Package type radio button menu

The menu uses ANSI escape codes for visual feedback:

• ❯ indicates current selection
• Underline for selected option
• Cursor hidden during navigation

Sources: src/cli/init_command.zig43-143

Generated Files

bun init creates the following files:

package.json

For executable type, adds:

tsconfig.json

.gitignore

node_modules
dist
*.log
.DS_Store

index.ts (entry point)

Sources: src/cli/init_command.zig1-300 test/cli/init/init.test.ts6-150

Non-Interactive Mode

With the -y flag, bun init uses default values without prompts:

Defaults:

• name: Current directory name
• version: "0.0.1"
• type: "module"
• entry: "index.ts"

Sources: test/cli/init/init.test.ts6-30

Common CLI Options

Options shared across multiple package commands:

Registry Configuration

The registry configuration supports:

• URL with authentication tokens
• Scoped registries for organization packages
• Environment variable expansion in URLs

Sources: test/cli/install/bun-install.test.ts400-460 src/install/npm.zig196-378

Network Options

The --network-concurrency option limits parallel HTTP requests to prevent overwhelming servers or hitting rate limits. The implementation tracks concurrent requests and enforces the limit in the download pipeline.

Sources: test/cli/install/bun-install.test.ts106-206

Path Options

Sources: test/harness.ts37-63

Error Handling and Validation

Package Validation

Commands validate package specifiers before processing:

Sources: src/install/dependency.zig153-280 test/cli/install/bun-add.test.ts95-126

Connection Errors

Network errors are reported with context:

error: ConnectionRefused downloading package manifest bar
error: GET http://localhost:PORT/bar - 404

Sources: test/cli/install/bun-install.test.ts341-398

Integrity Failures

If tarball checksums don't match:

error: Integrity check failed for tarball: package-name

The integrity is verified in ExtractTarball.run() before extraction.

Sources: src/install/extract_tarball.zig13-27

---

Sources: src/install/install.zig1-291 src/install/lockfile.zig1-800 src/install/dependency.zig1-900 src/install/npm.zig1-400 src/install/extract_tarball.zig1-300 src/install/migration.zig1-200 test/cli/install/bun-install.test.ts1-850 test/cli/install/bun-add.test.ts1-900 test/cli/install/bun-remove.test.ts1-200 test/cli/install/bun-update.test.ts1-250 test/cli/install/bun-link.test.ts1-300