bun link

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.

Global link directory

Globally-linked packages are stored in:

• macOS/Linux: ~/.bun/install/global/node_modules
• Windows: %USERPROFILE%\.bun\install\global\node_modules

Examples

Link a local package globally

$ 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).

Link multiple packages

cd ~/projects/my-app
bun link package-one package-two

Link in package.json

You can also use link: protocol directly in package.json:

{
  "dependencies": {
    "my-utils": "link:my-utils"
  }
}

Then run:

bun install

Link with relative path

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.

Comparison with npm link

bun link works similarly to npm link but with some differences:

Feature	Bun	npm
Speed	Instant	Slower
Global directory	~/.bun/install/global	{prefix}/lib/node_modules
Symlink behavior	Native implementation	Shell symlinks
Workspace support	Yes	Yes

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