terminal
terminal
dependencies unless you pass --dev, --optional, or --peer. If package.json already lists it in another group, Bun updates that entry in place.
--dev
Alias —
--development, -d, -D"devDependencies"):
terminal
--optional
To add a package as an optional dependency ("optionalDependencies"):
terminal
--peer
To add a package as a peer dependency ("peerDependencies"):
terminal
devDependencies entry is needed.
--exact
Alias —
-E--exact. Bun writes the exact version number to your package.json instead of a version range.
terminal
package.json:
package.json
terminal
--catalog
In a workspace, --catalog writes the version to the root package.json catalog and adds "catalog:" to the current package. --catalog=<name> uses a named catalog (workspaces.catalogs.<name>) and writes "catalog:<name>".
terminal
package.json
packages/app/package.json
- If the catalog already has an entry, Bun reuses it and writes only
"catalog:"to the current package. Pass an explicit version (bun add react@19 --catalog) to replace the entry — this affects every package that references it. - If you omit the version and the current
package.jsonalready has a range ("react": "^18.2.0"), Bun catalogs that range. - A package that already references
"catalog:<name>"keeps using that catalog. - Attach the name with
=:--catalog=testing, not--catalog testing. - Bun catalogs tarball and git specifiers under the package’s real name. It rejects relative paths and workspace packages.
bun add react (no version) writes "catalog:" if the default catalog already lists react. Pass a version to write a concrete range instead.
--filter
Alias —
-F!pattern excludes.
terminal
*matches every workspace package but not the root. To include the root, name it:--filter '*' --filter '<root-name>'.- If no workspace matches, Bun writes nothing and the command fails.
- Bun resolves local paths from the current directory and rewrites them relative to each selected package.
- Bun updates
bun.lockfor the whole repo but links only the selected workspaces intonode_modules, as withbun install --filter. - Cannot be combined with
--global.
--global
Alias —
bun add --global, bun add -g, bun install --global and bun install -g-g/--global flag. This does not modify the package.json of your current project. Use it to install command-line tools.
terminal
Configuring global installation behavior
Configuring global installation behavior
bunfig.toml
Trusted dependencies
Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such aspostinstall. These scripts represent a potential security risk, as they can execute arbitrary code on your machine.
To tell Bun to allow lifecycle scripts for a particular package, add the package to trustedDependencies in your package.json.
package.json
my-trusted-package.
Git dependencies
To add a dependency from a public or private git repository:terminal
To install private repositories, your system needs the appropriate SSH credentials to access the repository.
github, git, git+ssh, and git+https.
package.json
Tarball dependencies
A package name can correspond to a publicly hosted.tgz file. Bun downloads and installs the package from that tarball URL rather than from the package registry.
terminal
bun add writes the URL to your package.json:
package.json
CLI Usage
Dependency Management
Add the resolved version to the root
package.json catalog and depend on it as catalog:;
—catalog=NAME targets catalogs.NAMEProject Files & Lockfiles
Installation Control
Skip lifecycle scripts for all packages, including the project’s
package.json and trusted dependenciesRecursively analyze & install dependencies of files passed as arguments (using Bun’s bundler). Alias:
-aNetwork & Registry
Performance & Resource
Platform-specific optimizations for installing dependencies. Possible values:
clonefile (default on
macOS), hardlink (default on Linux and Windows), symlink, copyfile