bun pm pkg examples
Examples of `bun pm pkg` operations: `bun pm pkg get name` retrieves a single property, `bun pm pkg get name version` retrieves multiple properties, `bun pm pkg get` retrieves entire package.json, `bun pm pkg get scripts.build` retrieves nested property, `bun pm pkg set name="my-package"` sets a simple property, `bun pm pkg set scripts.test="jest" version=2.0.0` sets multiple properties, `bun pm pkg set private=true --json` sets JSON values with --json flag, `bun pm pkg delete description` deletes a single property, `bun pm pkg delete scripts.test contributors[0]` deletes multiple/nested properties, `bun pm pkg fix` auto-fixes common issues.
bun pm pkg manages package.json data
The `bun pm pkg` command manages `package.json` data with get, set, delete, and fix operations. All commands support dot and bracket notation for accessing properties.
bun pm pack creates tarball
The `bun pm pack` command creates a `.tgz` file containing all files that would be published to npm, following the same rules as `npm pack`.
bun pm pack options
The `bun pm pack` command supports the following options: `--dry-run` (perform all tasks except writing the tarball to disk, shows what would be included), `--destination <dir>` (the directory to save the tarball in), `--filename <name>` (an exact file name for the tarball), `--ignore-scripts` (skip running pre/postpack and prepare scripts), `--gzip-level <0-9>` (set the gzip compression level, from 0 to 9, default 9), `--quiet` (print only the tarball filename, suppressing the rest of the output, useful in scripts). Note: `--filename` and `--destination` cannot be used at the same time.
bun pm pack example with quiet mode
The `bun pm pack --quiet` command outputs only the tarball filename. Example: `TARBALL=$(bun pm pack --quiet)` followed by `echo "Created: $TARBALL"` outputs `Created: my-package-1.0.0.tgz`.
bun pm pack example with destination
To save a tarball to a custom directory, use `bun pm pack --destination ./dist`, which saves the tarball in the `./dist/` directory.
bun pm bin prints bin directory path
The `bun pm bin` command prints the path to the `bin` directory for the local project, which is typically `/path/to/current/project/node_modules/.bin`. The `bun pm bin -g` command prints the path to the global `bin` directory, typically `<$HOME>/.bun/bin`.
bun pm ls lists installed dependencies
The `bun pm ls` command (or `bun list`) prints a list of installed dependencies in the current project and their resolved versions, excluding their dependencies.
bun pm ls --all lists all dependencies
The `bun pm ls --all` command (or `bun list --all`) prints all installed dependencies, including nth-order dependencies.
bun pm ls --trusted lists trusted dependencies
The `bun pm ls --trusted` command (or `bun list --trusted`) prints only trusted dependencies (those allowed to run lifecycle scripts). When `trustedDependencies` is set in `package.json`, Bun shows the packages from that list; otherwise it shows packages from its default trusted dependencies list.
bun pm whoami prints npm username
The `bun pm whoami` command prints your npm username. It requires you to be logged in with credentials in either `bunfig.toml` or `.npmrc`.
bun pm hash commands
The `bun pm hash` command generates and prints the hash of the current lockfile. The `bun pm hash-string` command prints the string used to hash the lockfile. The `bun pm hash-print` command prints the hash stored in the current lockfile.
bun pm cache commands
The `bun pm cache` command prints the path to Bun's global module cache. The `bun pm cache rm` command clears Bun's global module cache.
bun pm migrate converts lockfile without installing
The `bun pm migrate` command migrates another package manager's lockfile without installing anything.
bun pm untrusted lists untrusted dependencies
The `bun pm untrusted` command prints current untrusted dependencies with scripts that had their lifecycle scripts blocked during install.
bun pm trust enables scripts for untrusted dependencies
The `bun pm trust <names>` command runs scripts for untrusted dependencies and adds them to `trustedDependencies`. It supports the `--all` option to trust all untrusted dependencies.
bun pm default-trusted lists default trusted dependencies
The `bun pm default-trusted` command prints the default trusted dependencies list.
bun pm version manages package version
The `bun pm version` command displays current package version and help. It supports version increments: `patch`, `minor`, `major`, `prerelease`, `prepatch`, `preminor`, `premajor`, `from-git`, or specific versions like `1.2.3`. By default it creates a git commit and tag; pass `--no-git-tag-version` to skip them.
bun pm version options
The `bun pm version` command supports the following options: `--no-git-tag-version` (skip git operations), `--allow-same-version` (prevents throwing error if version is the same), `--message=<val>` or `-m` (custom commit message, use %s for version substitution), `--preid=<val>` (prerelease identifier, e.g. beta → 1.0.1-beta.0), `--force` or `-f` (bypass dirty git history check).
bun pm version example
Examples of `bun pm version` command usage: `bun pm version patch` bumps to patch version, `bun pm version 1.2.3 --no-git-tag-version` sets specific version without git operations, `bun pm version prerelease --preid beta --message "Release beta: %s"` creates a prerelease with beta identifier.
bun pm pkg notation support
The `bun pm pkg` command supports the following notation patterns: `scripts.build` (dot notation), `contributors[0]` (array access), `workspaces.0` (dot with numeric index), `scripts[test:watch]` (bracket for special characters).
bun why example with glob pattern
To check why all packages matching a pattern are installed, use: bun why "@types/*"
bun why command usage
The bun why command explains why a package is installed in your project by showing the dependency chain that led to it. Basic usage is: bun why <package>
bun why package argument
The <package> argument specifies the name of the package to explain. It supports glob patterns like @org/* or *-lodash.
bun why --top flag
The --top flag shows only the top-level dependencies instead of the complete dependency tree.
bun why --depth flag
The --depth <number> flag sets the maximum depth of the dependency tree to display.
bun why output includes dependency type
The bun why output shows the type of dependency (dev, peer, optional, or production) for each package in the dependency chain.
bun why output format with indentation
The bun why command displays the complete dependency tree by default, with indentation indicating the relationship hierarchy between packages.
bun why example with single package
To check why a specific package is installed, use: bun why react
bun why example with --top flag
To show only top-level dependencies, use: bun why express --top
bun why example with --depth flag
To limit the dependency tree depth, use: bun why express --depth 2
--filter example with multiple scripts
To run multiple scripts across all packages, use bun run --parallel --filter '*' build lint. This runs both build and lint scripts in each package in parallel.
--filter flag syntax and overview
The --filter (or -F) flag selects packages in a monorepo by pattern. Patterns match package names or package paths with full glob syntax. bun install and bun outdated support --filter, and you can use it to run scripts in multiple packages at once.
--filter package name patterns
Name patterns select packages by the name field in package.json using the syntax --filter <pattern>. For example, if you have packages pkg-a, pkg-b and other, you can match all of them with *, only pkg-a and pkg-b with pkg*, and a specific package with its full name.
--filter package path patterns
Path patterns start with ./ and select all packages in directories matching the pattern. For example, to match all packages in subdirectories of packages, use --filter './packages/**'. To match the package in packages/foo, use --filter ./packages/foo.
--filter with script execution syntax
To run scripts in multiple packages at once, use the syntax: bun --filter <pattern> <script>. Both scripts run in parallel, and a terminal UI shows their respective outputs.
--filter respects workspace configuration
Filters respect your workspace configuration: if your package.json specifies which packages are part of the workspace, --filter only matches those packages. In a workspace, --filter can run scripts in packages located anywhere in the workspace without needing to cd into the directory.
--parallel and --sequential flags with --filter
Combine --filter or --workspaces with --parallel or --sequential to run scripts across workspace packages with Foreman-style prefixed output. Each line of output is prefixed with the package and script name (pkg-a:build | ...). Without --filter/--workspaces, the prefix is just the script name (build | ...).
--no-exit-on-error flag for --filter
Use --no-exit-on-error with --parallel and --filter to continue running even if one package's script fails.
--if-present flag with --workspaces
Use --if-present with --workspaces to skip packages that don't have the requested script instead of erroring.
--filter respects package dependency order
Bun respects package dependency order when running scripts with --filter. If package foo depends on package bar in your workspace and both have a build script, when you run bun --filter '*' build, foo only starts once bar is done.
--filter example running scripts in parallel
To run a dev script in multiple packages at once, use bun --filter '*' dev. This runs the dev script from both packages/api and packages/frontend in parallel with a shared terminal UI.
--parallel --filter example with build script
To run the build script in all matching packages concurrently with prefixed output, use bun run --parallel --filter '*' build.
--sequential --workspaces example
To run a build script in all workspace packages sequentially, use bun run --sequential --workspaces build.
--filter package name field fallback
When a package's package.json has no name field, Bun uses the relative path from the workspace root instead for output prefixing.
--filter example with glob-matched scripts
To run glob-matched scripts across all packages, use bun run --parallel --filter '*' "build:*". This runs all scripts matching the build:* pattern in parallel.
--parallel --no-exit-on-error example
To continue running tests even if one package's test script fails, use bun run --parallel --no-exit-on-error --filter '*' test.
Cache configuration in bunfig.toml
The [install.cache] section in bunfig.toml contains three configuration options: dir (string, default ~/.bun/install/cache) specifies the cache directory; disable (boolean, default false) when true prevents loading from the global cache (though Bun may still write to node_modules/.cache); disableManifest (boolean, default false) when true always resolves the latest versions from the registry instead of using cached manifests.
Global cache location
Bun stores every package downloaded from the registry in a global cache at ~/.bun/install/cache by default. The cache location can be overridden by setting the BUN_INSTALL_CACHE_DIR environment variable. Packages are stored in subdirectories named like ${name}@${version}, allowing multiple versions of the same package to be cached simultaneously.
Global store directory structure
The global store layout is located at ~/.bun/install/cache/links/ with entries named as <storepath>-<entry_hash>. Each entry contains package files and symlinks to dependencies. Projects have a hidden hoisted layer at node_modules/.bun/ that contains symlinks pointing into the global store. A 16-hex entry_hash suffix encodes the entry's resolved dependency closure.
Packages that don't use global store: trusted dependencies
Packages listed in trustedDependencies or trusted via bun add --trust fall back to per-project node_modules/.bun/<storepath>/ directory because their lifecycle scripts may mutate the install directory, and a script running through a shared project symlink would mutate the shared copy.
Global store performance: warm installs 7x faster
With the global virtual store enabled, warm installs are approximately 7 times faster than without it. Warm installs are roughly 6.6× faster than using the hoisted linker. This speed improvement comes from using one symlink per package instead of copying or cloning every file.
Packages that don't use global store: workspace and file dependencies
Packages with workspace:, file:, or link: dependencies fall back to per-project node_modules/.bun/<storepath>/ directory because those resolve to project-local paths that other projects cannot access. Ineligibility propagates: if an entry links to an ineligible package, the entry itself becomes ineligible and project-local.
Peer dependencies in global store entries
Resolved peer dependencies — both required and optional — are folded into each global entry as dependency symlinks and contribute to its 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 store phantom dependency limitation
With the global store enabled, packages that are true phantom dependencies (requiring something they never declared in dependencies, peerDependencies, or peerDependenciesMeta) will not resolve correctly because packages realpath into <cache>/links/ instead of being under project node_modules/.bun/. The solution is to add the helper to the consuming package's dependencies or set globalStore = false.
Global store hoisting patterns limitation
publicHoistPattern and hoistPattern hoist into the project's node_modules, which packages inside the global store cannot reach. These patterns still work for resolving hoisted packages from your own source code, but not from packages stored globally.
Global store tools scanning node_modules
Tools that scan node_modules without following symlinks or that compare file paths by string equality may behave differently with the global store enabled. This is the same caveat as any pnpm-style layout.
Global store cache growth over time
Each unique (package, version, resolved-dependency-set) triple gets one directory in ~/.bun/install/cache/links/. The store grows over time as new versions and new peer-dependency combinations land across projects. Run bun pm cache rm to clear the cache including the global store; the next install repopulates only what that project needs.
Global store concurrency handling
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 renames it into place as the final step. The loser of the rename sees EEXIST and discards its identical staging tree. A published entry is always complete with no separate completeness sentinel.
Global store warm install benchmark results
Benchmark on 1,400-package React/webpack/Babel/jest fixture on Apple Silicon macOS: --linker isolated with global store achieved 124.8 ms wall time and 94 ms system time with 0 clonefileat calls and 4,957 total syscalls, versus 840.9 ms wall time for isolated without global store (which made 1,387 clonefileat calls) and 823.9 ms for hoisted linker (which made 1,387 clonefileat calls).