bun install basic usage
Use `bun install` to install all dependencies, devDependencies, and optionalDependencies from a project's package.json. Bun also installs peerDependencies by default. It writes a bun.lock lockfile to the project root.
Bun · Package manager · all subjects
install
74 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
bun install specific package version
To install a specific version of a package, use `bun install react@19.1.1`. To install the latest tag, use `bun install react@latest`.
bun install logging flags
Use `--verbose` flag for debug logging or `--silent` flag for no logging output during installation.
bun install lifecycle scripts security
Bun does not execute arbitrary lifecycle scripts like postinstall for installed dependencies for security reasons. To allow lifecycle scripts for a specific package, add it to the `trustedDependencies` array in package.json, then re-install.
bun install lifecycle script optimizations disable
To disable Bun's automatic optimizations for postinstall scripts of popular packages, use `BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install`. To disable the ignore scripts optimization, use `BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install`.
bun install global packages
Use `-g` or `--global` flag to install a package globally. Example: `bun install --global cowsay` or `bun install -g cowsay`. Globally installed packages can be run as commands.
bun install production mode
Use `--production` flag to install only production dependencies (excluding devDependencies).
bun install concurrent scripts flag
Use `--concurrent-scripts` flag to adjust the maximum number of concurrent lifecycle scripts during installation. Default is two times the reported cpu count or GOMAXPROCS.
bun install frozen lockfile
Use `--frozen-lockfile` flag to install exact versions specified in the lockfile without updating it. If package.json disagrees with bun.lock, Bun exits with an error. This ensures reproducible installs.
bun install omit flag
Use `--omit` flag to exclude specific dependency types from installation. Examples: `bun install --omit dev` excludes devDependencies; `bun install --omit=dev --omit=peer --omit=optional` excludes all three types.
bun install dry run
Use `--dry-run` flag to perform a dry run without actually installing any packages.
bun install non-npm dependencies
Bun supports installing dependencies from Git, GitHub, and local or remote tarballs in package.json. Examples include git URLs like `git+https://github.com/user/repo.git`, GitHub shortcuts like `github:user/repo`, and tarball URLs like `https://registry.npmjs.org/package/-/package-1.0.0.tgz`.
bun install linker hoisted strategy
Use `bun install --linker hoisted` for the traditional npm/Yarn approach that flattens dependencies into a shared node_modules directory.
bun install linker isolated strategy
Use `bun install --linker isolated` for a pnpm-like approach that creates strict dependency isolation in node_modules/.bun/ with symlinks in top-level node_modules. This prevents phantom dependencies.
bun install default linker strategy
The default linker strategy depends on context: new workspaces/monorepos default to isolated; new single-package projects default to hoisted; existing projects made pre-v1.3.2 default to hoisted. The default is controlled by configVersion in the lockfile.
bun install minimum release age
Use `--minimum-release-age` flag to specify a minimum age (in seconds) for npm packages to protect against supply chain attacks. Example: `bun add @types/bun --minimum-release-age 259200` only installs versions published at least 3 days ago.
bunfig.toml install configuration
Bun looks for bunfig.toml in $XDG_CONFIG_HOME/.bunfig.toml, $HOME/.bunfig.toml, or ./bunfig.toml. If both global and local files exist, they are merged. Configuration options include: optional (default true), dev (default true), peer (default true), production (default false), saveTextLockfile (default true), frozenLockfile (default false), dryRun (default false), concurrentScripts (default cpu count or GOMAXPROCS times 2), linker (default hoisted or isolated based on context), minimumReleaseAge (default 259200), and minimumReleaseAgeExcludes.
bun install environment variables
Environment variables take priority over bunfig.toml for install configuration. Available variables: BUN_CONFIG_REGISTRY (set npm registry, default https://registry.npmjs.org), BUN_CONFIG_TOKEN (auth token for default registry), BUN_CONFIG_YARN_LOCKFILE (save Yarn v1-style yarn.lock), BUN_CONFIG_SKIP_SAVE_LOCKFILE (don't save lockfile), BUN_CONFIG_SKIP_LOAD_LOCKFILE (don't load lockfile), BUN_CONFIG_SKIP_INSTALL_PACKAGES (don't install packages).
bun install backend flag
Use `--backend` flag to specify the installation method. Options: hardlink (default on Linux), clonefile (default on macOS), clonefile_each_dir (macOS only, slower), copyfile (fallback when others fail), symlink (internal use for file: dependencies).
bun install cache location
Bun stores installed packages from npm in ~/.bun/install/cache/${name}@${version}. If the semver version has a build or pre tag, Bun replaces it with a hash. Delete cache with `bun pm cache rm` or `rm -rf ~/.bun/install/cache`.
bun ci command
Use `bun ci` (equivalent to `bun install --frozen-lockfile`) for CI/CD environments to ensure reproducible builds. It installs exact versions from bun.lock and fails if package.json doesn't match the lockfile. Requires bun.lock to be committed to version control.
bun install cpu and os flags
Use `--cpu` and `--os` flags to override the target platform for package selection. Example: `bun install --cpu=x64 --os=linux`. Accepted values for --cpu: arm, arm64, ia32, mips, mipsel, ppc, ppc64, s390, s390x, x32, x64. Accepted values for --os: aix, darwin, freebsd, linux, openbsd, sunos, win32, android.
bun install peer dependencies
Bun handles peer dependencies like Yarn, installing them automatically. If a dependency is marked optional in peerDependenciesMeta, Bun uses an existing dependency if possible.
bun lockfile format
bun.lock is Bun's lockfile format in text format. Prior to Bun 1.2, the lockfile was binary and called bun.lockb. To upgrade an old lockfile, run `bun install --save-text-lockfile --frozen-lockfile --lockfile-only`, then delete bun.lockb.
bun install pnpm migration
Bun automatically migrates projects from pnpm. When a pnpm-lock.yaml file is detected and no bun.lock exists, Bun converts the lockfile to bun.lock during installation. The original pnpm-lock.yaml remains unmodified. Migration requires pnpm lockfile version 7 or higher and only runs when bun.lock is absent with no opt-out flag.
bun install pnpm workspace migration
When migrating from pnpm, Bun moves pnpm-workspace.yaml configuration to package.json workspaces field. The catalog, catalogs, packages list, overrides, and patchedDependencies are migrated to the root package.json.
bun install pnpm catalog dependencies
Dependencies using pnpm's catalog: protocol are preserved during migration. Examples: `"react": "catalog:"` uses the default catalog entry; `"webpack": "catalog:build"` uses the named build catalog.
--filter with bun install
By default, bun install installs dependencies for every package in the monorepo. To install dependencies for specific packages, use --filter. Multiple --filter flags can be combined, such as --filter '!./' --filter './packages/*' to exclude the root package.json while including packages in ./packages.
--filter example with negation
To exclude specific packages from a filter, use the negation operator. For example, bun install --filter '!pkg-c' installs dependencies for all workspaces except pkg-c.
--filter example with path glob
To install dependencies for packages in ./packages, use bun install --filter './packages/*'. This matches all packages in subdirectories of packages.
Symlink backend example
bun install --backend symlink node --preserve-symlinks ./foo.js
Cached package reuse during install
When installing a package, if the cache already contains a version in the range specified by package.json, Bun uses the cached copy instead of downloading it again.
Pre-release and build suffix handling in cache
If a semver version has a pre-release suffix (1.0.0-beta.0) or a build suffix (1.0.0+20220101), it is replaced with a hash of that value instead in the cache directory name. This reduces the chance of errors from long file paths.
Installation verification and caching logic
When the node_modules folder exists, Bun first checks that it contains all expected packages with appropriate versions. If satisfied, bun install completes immediately. If a package is missing or has an incompatible version, Bun checks the cache for a compatible module. If found in cache, it is installed into node_modules. Otherwise, Bun downloads from the registry then installs it. Bun uses a custom JSON parser that stops parsing as soon as it finds "name" and "version".
Fast copying syscalls for cache installation
Once a package is in the cache, Bun copies files into node_modules using the fastest available syscalls: hardlinks on Linux, clonefile on macOS.
Disk space savings with hardlinks and clonefile
On Linux and Windows, Bun uses hardlinks to copy modules into node_modules, so package contents exist in a single location on disk, greatly reducing node_modules disk usage. On macOS, Bun uses clonefile which is copy-on-write: the clone occupies no extra disk space initially but counts towards the drive's limit. Because the copy only happens on write, patching node_modules in one project cannot affect other installations.
Installation backend strategies
The --backend flag is used to configure installation strategy and is respected by all of Bun's package management commands. Available backends are: hardlink (default on Linux and Windows), clonefile (default on macOS), clonefile_each_dir (macOS only, clones each file individually per directory, slower than clonefile), copyfile (fallback when others fail, slowest option, uses fcopyfile() on macOS and copy_file_range() on Linux), and symlink (used only for file: and eventually link: dependencies, skips symlinking the node_modules folder to prevent infinite loops).
Symlink backend with Node.js preservation
If installing with --backend=symlink, Node.js won't resolve node_modules of dependencies unless each dependency has its own node_modules folder or you pass --preserve-symlinks to node. Bun's runtime also supports --preserve-symlinks.
Isolated installs prevent phantom dependencies
Isolated installs create a non-hoisted dependency structure where packages can only access their explicitly declared dependencies, preventing phantom dependencies where packages import dependencies they never declared. This differs from traditional hoisted installation where dependencies are flattened into a shared node_modules directory.
Isolated installs peer dependency encoding in store path
Isolated installs encode peer dependencies in the store path directory name. For example, a package with peer dependencies creates a specialized path like node_modules/.bun/package@1.0.0_react@18.2.0/, where the directory name includes both the package version and its peer dependency versions, ensuring each unique combination gets its own installation.
bun install --linker flag for isolated and hoisted installation
The --linker flag specifies the installation strategy for bun install. Use 'bun install --linker isolated' for isolated installs or 'bun install --linker hoisted' for traditional hoisted installs. The linker strategy can also be set in bunfig.toml with [install] linker = "isolated" or [install] linker = "hoisted".
Isolated installs default behavior by configVersion and workspace usage
The default linker strategy depends on the project's lockfile configVersion and whether workspaces are used. For configVersion 1 with workspaces, the default linker is isolated. For configVersion 1 without workspaces, configVersion 0 with workspaces, or configVersion 0 without workspaces, the default linker is hoisted. New projects default to configVersion 1. Existing Bun projects made before v1.3.2 without a version set configVersion to 0, preserving hoisted linker defaults. Migrations from pnpm use configVersion 1 with isolated installs in workspaces. Migrations from npm or yarn use configVersion 0 with hoisted installs.
Isolated installs directory structure with .bun central store
Isolated installs create a two-tier structure: a central package store at node_modules/.bun with versioned package installations like node_modules/.bun/package@1.0.0/node_modules/package, scoped packages stored as @scope+package@2.1.0 with / replaced by +, and top-level node_modules containing symlinks pointing to the central store entries.
install.hoist = false for strict resolution in isolated installs
Setting install.hoist = false (or hoist=false in .npmrc) in bunfig.toml disables the creation of node_modules/.bun/node_modules fallback directory, causing undeclared imports to fail instead of resolving from hoisted dependencies. However, the root node_modules remains above the store, so direct dependencies, publicHoistPattern matches, and workspace packages stay resolvable from store packages.
bun install --linker isolated --verbose for debugging
Enable verbose logging for isolated installs debugging with 'bun install --linker isolated --verbose'. Verbose output shows store entry creation, symlink operations, peer dependency resolution, and deduplication decisions.
Isolated installs key benefits
Key benefits of isolated installs include preventing phantom dependencies, deterministic resolution producing the same dependency tree regardless of other installed packages, better isolation for monorepos preventing cross-contamination between packages, and reproducible builds with more predictable resolution behavior across environments.
Workspace packages in isolated installs symlinked to source
In monorepos with isolated installs, workspace packages are symlinked directly to their source directories, not the store. Workspace dependencies can access other workspace packages in the monorepo, while external dependencies are installed in the isolated store.
install.globalStore for 7x faster warm installs
When install.globalStore is enabled, store entries are materialized once into a global virtual store at <cache>/links/ and node_modules/.bun/<pkg>@<ver> becomes a symlink into it. This makes warm installs after 'rm -rf node_modules' approximately 7x faster on typical mid-size projects by creating one symlink per package instead of copying every package's files. Global store is off by default.
Backend materialization strategies for isolated installs
When the global store is disabled (default) or an entry isn't eligible for it, Bun materializes entries using one of: Clonefile on macOS for copy-on-write filesystem clones, Hardlink on Linux/Windows to save disk space, or Copyfile as fallback for full file copies when other methods aren't available.
When to use isolated installs vs hoisted installs
Use isolated installs when working in monorepos with multiple packages, strict dependency management is required, preventing phantom dependencies is important, or building libraries needing deterministic dependencies. Use hoisted installs when working with legacy code assuming flat node_modules, compatibility with existing build tools is required, working in environments where symlinks aren't well supported, or preferring simpler traditional npm behavior.
Migration from npm/Yarn to isolated installs
To migrate from npm or Yarn to isolated installs: remove existing node_modules and lockfiles with 'rm -rf node_modules package-lock.json yarn.lock', then install with isolated linker using 'bun install --linker isolated'.
Migration from pnpm to isolated installs
To migrate from pnpm to isolated installs: remove pnpm files with 'rm -rf node_modules pnpm-lock.yaml', then install with Bun's isolated linker using 'bun install --linker isolated'. Isolated installs are conceptually similar to pnpm, with the main difference being Bun uses symlinks in node_modules while pnpm uses a global store with symlinks.
Comparison table: Hoisted vs Isolated installs
Comparison of aspects between hoisted (npm/Yarn) and isolated (pnpm-like) installs: Dependency access - Hoisted allows packages to access any hoisted dependency, Isolated only allows seeing declared dependencies. Phantom dependencies - Hoisted enables them (❌), Isolated prevents them (✅). Disk usage - Hoisted is lower with shared installs (✅), Isolated is similar using symlinks (✅). Determinism - Hoisted is less deterministic (❌), Isolated is more deterministic (✅). Node.js compatibility - Both are compatible (✅). Best for - Hoisted suits single projects and legacy code, Isolated suits monorepos and strict dependency management.
Install configuration in bunfig.toml
Install strategy can be configured in bunfig.toml using [install] section with linker = "isolated" or linker = "hoisted", and hoist = false or hoist = true for the fallback directory. This configuration can be set globally in $HOME/.bunfig.toml or per-project.
Isolated installs compatibility issues with certain packages
Some packages may not work correctly with isolated installs due to hardcoded paths assuming flat node_modules structure, dynamic imports that don't follow Node.js resolution, or build tools that scan node_modules directly. If issues occur, switch to hoisted mode with 'bun install --linker hoisted' or report compatibility issues.
postinstall script use cases
The postinstall script is widely used to build or install platform-specific binaries for packages that are implemented as native Node.js add-ons. For example, node-sass uses postinstall to build a native binary for Sass.
--ignore-scripts flag disables all lifecycle scripts
Use the --ignore-scripts flag to disable lifecycle scripts for all packages: bun install --ignore-scripts
install.ignoreScripts bunfig.toml setting
Set install.ignoreScripts = true in bunfig.toml to make --ignore-scripts the default for a project.
bun.lock should be committed to git
The `bun.lock` lockfile should be committed to version control with git.
bun install creates bun.lock lockfile
The `bun install` command creates a lockfile called `bun.lock`.