bun i -g installs packages globally
bun i -g <package> installs a package globally. By default, globally-installed packages go into a .bun/install/global/node_modules folder inside the home directory.
Bun · Package manager · all subjects
install: global store
29 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
npm registry metadata caching
Bun uses a binary format for caching npm registry responses, which loads faster than JSON and is smaller on disk. These files live in '~/.bun/install/cache/*.npm'. The filename pattern is '${hash(packageName)}.npm' using a hash so Bun doesn't need extra directories for scoped packages. Bun's usage of Cache-Control ignores Age, which improves performance but means Bun may be about 5 minutes behind the latest package version metadata from npm.
Global package 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 of that value to reduce chances of errors from long file paths.
Clear bun install cache
To delete the cache, run 'bun pm cache rm' or 'rm -rf ~/.bun/install/cache'.
Global installation configuration in bunfig.toml
Configure global installation behavior with `[install]` section in bunfig.toml. Use `globalDir` to set where `bun add --global` installs packages (default: `~/.bun/install/global`), and `globalBinDir` to set where globally-installed package bins are linked (default: `~/.bun/bin`).
Global virtual store for isolated installs
When install.globalStore is enabled, Bun materializes store entries once into a global virtual store at <cache>/links/, and node_modules/.bun/<pkg>@<ver> becomes a symlink into it. Warm installs after rm -rf node_modules only create one symlink per package instead of copying every package's files, making it roughly 7× faster on a typical mid-size project. The global store is off by default; it can be enabled in bunfig.toml.
Pre-release and build suffix handling in cache
If the semver version has a pre-release suffix (1.0.0-beta.0) or a build suffix (1.0.0+20220101), Bun replaces the suffix with a hash of that value instead, to reduce the chance of errors from long file paths.
Fast copying with platform-specific syscalls
Once a package is downloaded into the cache, Bun copies files into node_modules using the fastest available syscalls: hardlinks on Linux and Windows, and clonefile on macOS.
Hardlinks for disk space savings on Linux and Windows
On Linux and Windows, Bun uses hardlinks to "copy" a module into a project's node_modules directory, so the contents of the package only exist in a single location on disk. This greatly reduces the disk space used by node_modules.
Global cache directory location
Bun stores every package downloaded from the registry in a global cache at ~/.bun/install/cache. The location can be overridden with the BUN_INSTALL_CACHE_DIR environment variable. Packages are stored in subdirectories named ${name}@${version}, allowing Bun to cache multiple versions of a single package.
Clonefile for disk space savings on macOS
On macOS, Bun uses clonefile, which is copy-on-write: the clone occupies no extra disk space initially, but it counts towards the drive's limit. Because the copy only happens on write, patching node_modules/* in one project cannot affect other installations.
Cache configuration in bunfig.toml
The [install.cache] section in bunfig.toml supports three configuration options: dir (the directory to use for the cache, defaults to ~/.bun/install/cache), disable (when true, don't load from the global cache, though Bun may still write to node_modules/.cache, defaults to false), and disableManifest (when true, always resolve the latest versions from the registry, defaults to false).
Global virtual store cache growth and cleanup
Each unique (package, version, resolved-dependency-set) triple gets one directory in <cache>/links/. The store grows over time as new versions and peer-dependency combinations are installed. Run bun pm cache rm to clear the entire cache including the global store; the next install repopulates only what the project needs.
Global virtual store concurrent installation safety
Multiple bun install processes may race to populate the same global entry. Each process builds the entry under a private <entry>.tmp-<random>/ staging directory and then renames it into place. The loser of the rename sees EEXIST and discards its identical staging tree. A published entry is always complete; there is no separate completeness sentinel.
Global virtual store why it is fast - warm path optimization
With the global store enabled, the warm path for installation is one access() syscall (checking if the global entry exists) plus one symlink() syscall (pointing the project at it) per package. This contrasts with the isolated linker without global store, which calls clonefileat() for every package on every install.
Enable global virtual store via environment variable
To enable the global virtual store per invocation, set the environment variable BUN_INSTALL_GLOBAL_STORE=1 when running bun install --linker isolated.
Global virtual store default disabled state
The global virtual store is off by default. It only applies to the isolated linker; the hoisted linker does not use it.
Enable global virtual store in bunfig.toml
To enable the global virtual store for a project, set [install] linker = "isolated" and globalStore = true in bunfig.toml.
Disable global virtual store
To explicitly opt out of the global virtual store (the default), set globalStore = false in bunfig.toml or BUN_INSTALL_GLOBAL_STORE=0 in the environment.
Global virtual store warm install performance
With the global virtual store enabled, warm CI installs are roughly 6.7× faster than the same linker without the global store and 6.6× faster than the hoisted linker. On a 1,400-package React/webpack/Babel/jest fixture on Apple Silicon macOS, warm installs took 124.8 ms with the global store enabled versus 840.9 ms without it.
Global virtual store disk usage reduction
With the global virtual store, node_modules shrinks from hundreds of megabytes per project to roughly 5 MB of symlinks per project, while shared packages are stored once on disk (391 MB for the fixture). For five clones of the same project, the difference is approximately 2 GB of duplicated files versus 400 MB total.
Global virtual store real-world warm install timings
Real-world projects show significant warm install improvements with global store: cal.com (~3,580 packages) improves from 37.4s cold to 4.7s warm; remix (~1,750 packages) from 23.1s to 2.0s; excalidraw (~1,332 packages) from 5.9s to 1.1s; hono (~790 packages) from 4.5s to 1.3s; next build with create-next-app (~382 packages) from 1.0s to 0.35s.
Global virtual store directory structure
The global virtual store uses a directory structure at ~/.bun/install/cache/links/ containing entries named <storepath>-<entry_hash>, where entry_hash is a 16-hex suffix encoding the entry's resolved dependency closure. Each project's node_modules contains symlinks into .bun/ which point to the global store. The entry hash encodes the package's store path, tarball integrity, and hashes of all dependencies, ensuring projects with different dependency resolutions get separate global entries.
Packages that stay project-local instead of global store
An entry stays project-local and does not use the global store when: the package has a patch applied via bun patch; the package is listed in trustedDependencies or trusted via bun add --trust; the package or any dependency it links to is a workspace:, file:, or link: dependency. Ineligibility propagates, so if a package depends on an ineligible package, it also becomes ineligible.
Global virtual store peer dependency handling
Bun folds resolved peer dependencies (required and optional) into each global entry as dependency symlinks. These peer dependencies contribute to the entry's hash. Bun synthesizes an implicit "*" optional peer for packages that list a name only in peerDependenciesMeta without a matching peerDependencies entry, matching pnpm and yarn behavior.
Global virtual store phantom dependency fallback issue
With the global store, packages realpath into <cache>/links/, so the hidden hoisted layer at node_modules/.bun/node_modules/ is no longer on the resolution path from inside a package. This affects packages doing require() for undeclared dependencies (true phantom dependencies). To fix this, add the helper to the consuming package's dependencies or set globalStore = false.
Global virtual store and hoisting patterns compatibility
publicHoistPattern and hoistPattern hoist packages into the project's node_modules, which packages inside the global store cannot reach. These patterns still work for resolving hoisted packages from the project's own source code.
cache option in .npmrc
The cache option sets the cache directory path or disables caching. Use cache=/path/to/cache to set a custom directory, or cache=false to disable caching entirely.
--lockfile-only populates global install cache
The --lockfile-only flag still populates the global install cache with registry metadata and git/tarball dependencies.