Use bun link in a local directory to register the current package as a "linkable" package.

terminal

cd /path/to/cool-pkg
cat package.json
bun link

bun link v1.3.3 (7416672e)
Success! Registered "cool-pkg"

To use cool-pkg in a project, run:
  bun link cool-pkg

Or add it in dependencies in your package.json file:
  "cool-pkg": "link:cool-pkg"

You can now "link" this package into other projects using bun link cool-pkg. This command creates a symlink in the target project's node_modules directory pointing to the local directory.

terminal

cd /path/to/my-app
bun link cool-pkg

Pass --save to also add cool-pkg to the dependencies field of your app's package.json, with a version specifier that tells Bun to load from the registered local directory instead of installing from npm:

terminal

bun link --save cool-pkg

package.json

{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    "cool-pkg": "link:cool-pkg" 
  }
}

Linking a directory by path#

link: also accepts a path, as in Yarn and pnpm. The path is relative to the package.json that declares it, and Bun installs a symlink to that directory. Nothing has to be registered with bun link first.

package.json

{
  "dependencies": {
    "design-tokens": "link:./vendor/design-tokens",
    "shared": "link:../shared"
  }
}

Anything that is not a package name is a path: link:./dir, link:../dir, link:vendor/dir, an absolute path. link:dir and link:@scope/dir are names registered with bun link; write link:./dir for the directory.
The directory must exist. It does not need a package.json.
The directory's own dependencies are not installed. Use file: for a copy whose dependencies are installed, or make the directory a workspace.
Only your project may use a path: the root package.json, a workspace, a file: directory one of them depends on, or a top-level overrides / resolutions entry. bun install fails when a package from the registry, git or a tarball declares one, so replace a link: path before you publish a package.

Unlinking#

Use bun unlink in the root directory to unregister a local package.

terminal

cd /path/to/cool-pkg
bun unlink

bun unlink v1.3.3 (7416672e)
success: unlinked package "cool-pkg"

CLI Usage#

bun link <packages>

Installation Scope#

--globalboolean

Has no effect: bun link always registers packages in the global folder. Alias: -g

Dependency Management#

--productionboolean

Don't install devDependencies. Alias: -p

--omitstring

Exclude dev, optional, or peer dependencies from install

Project Files & Lockfiles#

--yarnboolean

Write a yarn.lock file (yarn v1). Alias: -y

--frozen-lockfileboolean

Disallow changes to lockfile

--save-text-lockfileboolean

Save a text-based lockfile

--lockfile-onlyboolean

Generate a lockfile without installing dependencies

--no-saveboolean

Don't update package.json or save a lockfile (the default)

--saveboolean

Update package.json and save a lockfile (false by default)

--trustboolean

Add to trustedDependencies in the project's package.json and install the package(s)

Installation Control#

--forceboolean

Always request the latest versions from the registry & reinstall all dependencies. Alias: -f

--no-verifyboolean

Skip verifying integrity of newly downloaded packages

--backendstring

Platform-specific optimizations for installing dependencies. One of clonefile, hardlink, symlink, or copyfile

--linkerstring

Linker strategy (one of isolated or hoisted)

--dry-runboolean

With bun link <package>, resolve but don't install packages, update package.json, or save a lockfile. Has no effect on bare bun link, which still registers the current package

--ignore-scriptsboolean

Skip lifecycle scripts for all packages, including the project's package.json and trusted dependencies

Network & Registry#

--castring

Provide a Certificate Authority signing certificate

--cafilestring

Same as --ca, but as a file path to the certificate

--use-system-caboolean

Use the system's trusted certificate authorities

--registrystring

Use a specific registry by default, overriding .npmrc, bunfig.toml, and environment variables

--network-concurrencynumberdefault:64

Maximum number of concurrent network requests

Performance & Resource#

--concurrent-scriptsnumber

Maximum number of concurrent jobs for lifecycle scripts (default: 2x CPU cores)

Caching#

--cache-dirstring

Store & load cached data from a specific directory path

--no-cacheboolean

Ignore manifest cache entirely

Output & Logging#

--silentboolean

Don't log anything

--quietboolean

Disable the progress bar

--verboseboolean

Excessively verbose logging

--no-progressboolean

Disable the progress bar

--no-summaryboolean

Don't print a summary

Platform Targeting#

--cpustring

Override CPU architecture for optional dependencies (e.g., x64, arm64, * for all)

--osstring

Override operating system for optional dependencies (e.g., linux, darwin, * for all)

--libcstring

Override libc for optional dependencies (e.g., glibc, musl, * for all)

Global Configuration & Context#

--configstring

Specify path to config file (bunfig.toml). Alias: -c

--cwdstring

Set a specific current working directory

--env-filestring

Load environment variables from the specified file(s)

--no-env-fileboolean

Disable automatic loading of .env files

Help#

--helpboolean

Print this help menu. Alias: -h