温馨提示：本站仅提供公开网络链接索引服务，不存储、不篡改任何第三方内容，所有内容版权归原作者所有
AI智能索引来源：http://www.bun.com/docs/pm/isolated-installs
点击访问原文链接

Isolated installs - Bun

进入原网站 导航首页
Isolated installs - BunSkip to main contentBun home pageSearch...⌘KInstall BunSearch...NavigationAdvanced ConfigurationIsolated installsRuntimePackage ManagerBundlerTest RunnerGuidesReferenceBlogFeedbackdiv:first-child]:!hidden peer-[.is-custom]:[&>div:first-child]:sm:!hidden peer-[.is-custom]:[&>div:first-child]:md:!hidden peer-[.is-custom]:[&>div:first-child]:lg:!hidden peer-[.is-custom]:[&>div:first-child]:xl:!hidden">Core Commandsbun installbun addbun removebun updatebunxPublishing & Analysisbun publishbun outdatedbun whybun auditbun infoWorkspace ManagementWorkspacesCatalogsbun linkbun pmAdvanced Configurationbun patchbun --filterGlobal cacheIsolated installsLockfileLifecycle scriptsScopes and registriesOverrides and resolutionsSecurity Scanner API.npmrc supportOn this pageWhat are isolated installs?Key benefitsUsing isolated installsCommand lineConfiguration fileDefault behaviorHow isolated installs workDirectory structureResolution algorithmWorkspace handlingComparison with hoisted installsAdvanced featuresPeer dependency handlingBackend strategiesDebugging isolated installsTroubleshootingCompatibility issuesPerformance considerationsMigration guideFrom npm/YarnFrom pnpmWhen to use isolated installsRelated documentationAdvanced ConfigurationIsolated installsCopy pagespan]:line-clamp-1 overflow-hidden group flex items-center py-0.5 gap-1 text-sm text-gray-950/50 dark:text-white/50 group-hover:text-gray-950/70 dark:group-hover:text-white/70 rounded-none rounded-r-xl border px-3 border-gray-200 aspect-square dark:border-white/[0.07] bg-background-light dark:bg-background-dark hover:bg-gray-600/5 dark:hover:bg-gray-200/5" aria-label="More actions" type="button" id="radix-_R_2shjinpfd9rqaabsnpfdb_" aria-haspopup="menu" aria-expanded="false" data-state="closed">*]:[overflow-wrap:anywhere]">Strict dependency isolation similar to pnpm’s approach

Copy pagespan]:line-clamp-1 overflow-hidden group flex items-center py-0.5 gap-1 text-sm text-gray-950/50 dark:text-white/50 group-hover:text-gray-950/70 dark:group-hover:text-white/70 rounded-none rounded-r-xl border px-3 border-gray-200 aspect-square dark:border-white/[0.07] bg-background-light dark:bg-background-dark hover:bg-gray-600/5 dark:hover:bg-gray-200/5" aria-label="More actions" type="button" id="radix-_R_5hjinpfd9rqaabsnpfdb_" aria-haspopup="menu" aria-expanded="false" data-state="closed">Bun provides an alternative package installation strategy called isolated installs that creates strict dependency isolation similar to pnpm’s approach. This mode prevents phantom dependencies and ensures reproducible, deterministic builds. This is the default installation strategy for new workspace/monorepo projects (with configVersion = 1 in the lockfile). Existing projects continue using hoisted installs unless explicitly configured. ​What are isolated installs? Isolated installs create a non-hoisted dependency structure where packages can only access their explicitly declared dependencies. This differs from the traditional “hoisted” installation strategy used by npm and Yarn, where dependencies are flattened into a shared node_modules directory. ​Key benefits Prevents phantom dependencies — Packages cannot accidentally import dependencies they haven’t declared Deterministic resolution — Same dependency tree regardless of what else is installed Better for monorepos — Workspace isolation prevents cross-contamination between packages Reproducible builds — More predictable resolution behavior across environments ​Using isolated installs ​Command line Use the --linker flag to specify the installation strategy: terminalCopy# Use isolated installs bun install --linker isolated # Use traditional hoisted installs bun install --linker hoisted ​Configuration file Set the default linker strategy in your bunfig.toml or globally in $HOME/.bunfig.toml: bunfig.tomlCopy[install] linker = "isolated" ​Default behavior The default linker strategy depends on your project’s lockfile configVersion: configVersionUsing workspaces?Default Linker1✅isolated1❌hoisted0✅hoisted0❌hoisted New projects: Default to configVersion = 1. In workspaces, v1 uses the isolated linker by default; otherwise it uses hoisted linking. Existing Bun projects (made pre-v1.3.2): If your existing lockfile doesn’t have a version yet, Bun sets configVersion = 0 when you run bun install, preserving the previous hoisted linker default. Migrations from other package managers: From pnpm: configVersion = 1 (using isolated installs in workspaces) From npm or yarn: configVersion = 0 (using hoisted installs) You can override the default behavior by explicitly specifying the --linker flag or setting it in your configuration file. ​How isolated installs work ​Directory structure Instead of hoisting dependencies, isolated installs create a two-tier structure: tree layout of node_modulesCopynode_modules/ ├── .bun/ # Central package store │ ├── package@1.0.0/ # Versioned package installations │ │ └── node_modules/ │ │ └── package/ # Actual package files │ ├── @scope+package@2.1.0/ # Scoped packages (+ replaces /) │ │ └── node_modules/ │ │ └── @scope/ │ │ └── package/ │ └── ... └── package-name -> .bun/package@1.0.0/node_modules/package # Symlinks ​Resolution algorithm Central store — All packages are installed in node_modules/.bun/package@version/ directories Symlinks — Top-level node_modules contains symlinks pointing to the central store Peer resolution — Complex peer dependencies create specialized directory names Deduplication — Packages with identical package IDs and peer dependency sets are shared ​Workspace handling In monorepos, workspace dependencies are handled specially: Workspace packages — Symlinked directly to their source directories, not the store Workspace dependencies — Can access other workspace packages in the monorepo External dependencies — Installed in the isolated store with proper isolation ​Comparison with hoisted installs AspectHoisted (npm/Yarn)Isolated (pnpm-like)Dependency accessPackages can access any hoisted dependencyPackages only see declared dependenciesPhantom dependencies❌ Possible✅ PreventedDisk usage✅ Lower (shared installs)✅ Similar (uses symlinks)Determinism❌ Less deterministic✅ More deterministicNode.js compatibility✅ Standard behavior✅ Compatible via symlinksBest forSingle projects, legacy codeMonorepos, strict dependency management ​Advanced features ​Peer dependency handling Isolated installs handle peer dependencies through sophisticated resolution: tree layout of node_modulesCopy# Package with peer dependencies creates specialized paths node_modules/.bun/package@1.0.0_react@18.2.0/ The directory name encodes both the package version and its peer dependency versions, ensuring each unique combination gets its own installation. ​Backend strategies Bun uses different file operation strategies for performance: Clonefile (macOS) — Copy-on-write filesystem clones for maximum efficiency Hardlink (Linux/Windows) — Hardlinks to save disk space Copyfile (fallback) — Full file copies when other methods aren’t available ​Debugging isolated installs Enable verbose logging to understand the installation process: terminalCopybun install --linker isolated --verbose This shows: Store entry creation Symlink operations Peer dependency resolution Deduplication decisions ​Troubleshooting ​Compatibility issues Some packages may not work correctly with isolated installs due to: Hardcoded paths — Packages that assume a flat node_modules structure Dynamic imports — Runtime imports that don’t follow Node.js resolution Build tools — Tools that scan node_modules directly If you encounter issues, you can: Switch to hoisted mode for specific projects: terminalCopybun install --linker hoisted Report compatibility issues to help improve isolated install support ​Performance considerations Install time — May be slightly slower due to symlink operations Disk usage — Similar to hoisted (uses symlinks, not file copies) Memory usage — Higher during install due to complex peer resolution ​Migration guide ​From npm/Yarn terminalCopy# Remove existing node_modules and lockfiles rm -rf node_modules package-lock.json yarn.lock # Install with isolated linker bun install --linker isolated ​From pnpm Isolated installs are conceptually similar to pnpm, so migration should be straightforward: terminalCopy# Remove pnpm files rm -rf node_modules pnpm-lock.yaml # Install with Bun's isolated linker bun install --linker isolated The main difference is that Bun uses symlinks in node_modules while pnpm uses a global store with symlinks. ​When to use isolated installs Use isolated installs when: Working in monorepos with multiple packages Strict dependency management is required Preventing phantom dependencies is important Building libraries that need deterministic dependencies Use hoisted installs when: Working with legacy code that assumes flat node_modules Compatibility with existing build tools is required Working in environments where symlinks aren’t well supported You prefer the simpler traditional npm behavior ​Related documentation Package manager > Workspaces — Monorepo workspace management Package manager > Lockfile — Understanding Bun’s lockfile format CLI > install — Complete bun install command reference

Was this page helpful?

YesNoSuggest editsRaise issueGlobal cachePreviousLockfileNext⌘IxgithubdiscordyoutubePowered by

智能索引记录