Skip to main content
Remove a globally-linked package. 
bun unlink

​
Behavior

bun unlink removes a package from the global link registry. Run bun unlink (no arguments) in a package directory to remove its global registration: 
cd ~/projects/my-library
bun unlink
This removes the global link so other projects can no longer link to it.

​
Examples

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

success: unlinked package "my-utils"
The package is removed from the global registry. Other projects using bun link my-utils will no longer work until the package is re-linked.

​
What gets removed

When unlinking a package, Bun:
  1. Removes the symlink from global node_modules
  2. Removes any global bin links
  3. Leaves existing project links intact

​
Remove from a project

To remove a linked package from a specific project (without unlinking globally), use bun remove: 
cd ~/projects/my-app
bun remove my-utils

​
Flags

​
--cwd <path>

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

​
--global-dir <path>

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

​
Re-linking

To re-link a package after unlinking: 
cd ~/projects/my-library
bun link

​
Global bin directory

Globally-linked binaries are stored in:
  • macOS/Linux: ~/.bun/install/global/bin
  • Windows: %USERPROFILE%\.bun\install\global\bin
Unlinking removes binaries from this directory.

​
Use cases

​
Clean up after development

# Done developing a local package
cd ~/projects/my-lib
bun unlink

# Unlink from projects using it
cd ~/projects/my-app
bun remove my-lib
bun add my-lib  # Install from registry instead

​
Switch to published version

# Unlink local development version
cd ~/projects/my-package
bun unlink

# Install published version in app
cd ~/projects/my-app  
bun remove my-package
bun add my-package
If a package link is broken: 
cd ~/projects/package
bun unlink
bun link  # Re-register

​
Common issues

​
Package not linked

If running bun unlink shows “package is not globally linked”: 
$ bun unlink
success: package "my-package" is not globally linked, so there's nothing to do.
The package wasn’t linked globally. This is not an error.

​
Projects still reference the package

Unlinking doesn’t automatically remove the package from projects using it. You must manually remove it: 
cd ~/projects/app
bun remove my-package

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us