Skip to main content
Link a local package globally or use a globally-linked package. 
bun link [package]

​
Behavior

bun link has two modes:

​
Register a package (no arguments)

Run bun link in a package directory to register it globally: 
cd ~/projects/my-library
bun link
This creates a global link that other projects can reference.

​
Use a linked package

Run bun link <package> in another project to use the globally-linked package: 
cd ~/projects/my-app
bun link my-library
This creates a symlink in node_modules pointing to the globally-linked package. Globally-linked packages are stored in:
  • macOS/Linux: ~/.bun/install/global/node_modules
  • Windows: %USERPROFILE%\.bun\install\global\node_modules

​
Examples

$ cd ~/projects/my-utils
$ cat package.json
{
  "name": "my-utils",
  "version": "1.0.0"
}

$ bun link
bun link v1.0.0

Success! Registered "my-utils"

To use my-utils in a project, run:
  bun link my-utils

Or add it in dependencies in your package.json file:
  "my-utils": "link:my-utils"

​
Use a linked package in another project

$ cd ~/projects/my-app
$ bun link my-utils
bun link v1.0.0

 installed my-utils@link:my-utils

 1 package installed [23ms]
Now my-app can import from my-utils: 
import { something } from "my-utils";
Changes in my-utils are immediately reflected in my-app (no rebuild needed). 
cd ~/projects/my-app
bun link package-one package-two
You can also use link: protocol directly in package.json: 
{
  "dependencies": {
    "my-utils": "link:my-utils"
  }
}
Then run: 
bun install
Alternatively, use relative paths with file: protocol: 
{
  "dependencies": {
    "my-utils": "file:../my-utils"
  }
}

​
Binaries

If a linked package has a bin field, the binary is linked to the global bin directory: 
{
  "name": "my-cli",
  "bin": {
    "my-cli": "./cli.js"
  }
}
After bun link, the my-cli command is available globally: 
$ bun link
$ my-cli --version
1.0.0

​
Flags

​
--cwd <path>

Run command in specified directory. 
bun link --cwd ~/projects/my-library

​
--global-dir <path>

Use a custom global directory. 
bun link --global-dir /custom/path

​
Unlinking packages

To remove a global link: 
cd ~/projects/my-library
bun unlink
To remove a linked package from a project: 
cd ~/projects/my-app
bun remove my-utils
See bun unlink for details. bun link works similarly to npm link but with some differences:
FeatureBunnpm
SpeedInstantSlower
Global directory~/.bun/install/global{prefix}/lib/node_modules
Symlink behaviorNative implementationShell symlinks
Workspace supportYesYes

​
Common issues

​
Package not found

If bun link <package> fails with “not found”, ensure the package is registered: 
# Register the package first
cd ~/projects/package
bun link

# Then link it
cd ~/projects/app
bun link package

​
Changes not reflected

If changes in the linked package aren’t reflected:
  1. Ensure you’re using a symlink (check node_modules/package)
  2. Restart your development server
  3. For TypeScript, rebuild the linked package

​
Use cases

​
Local development

Develop a library and application simultaneously: 
# Terminal 1 - Library
cd ~/projects/my-lib
bun link

# Terminal 2 - Application  
cd ~/projects/my-app
bun link my-lib
npm run dev

​
Monorepos

For monorepos, consider using workspaces instead of bun link.

​
Testing unpublished packages

Test a package before publishing: 
cd ~/projects/new-package
bun link

cd ~/projects/test-app
bun link new-package
# Test the package

Build docs developers (and LLMs) love

Get started for freeTalk to us