> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# bun link

Link a local package globally or use a globally-linked package.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
$ 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

```bash theme={null}
$ 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`:

```ts theme={null}
import { something } from "my-utils";
```

Changes in `my-utils` are immediately reflected in `my-app` (no rebuild needed).

### Link multiple packages

```bash theme={null}
cd ~/projects/my-app
bun link package-one package-two
```

### Link in package.json

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

```json theme={null}
{
  "dependencies": {
    "my-utils": "link:my-utils"
  }
}
```

Then run:

```bash theme={null}
bun install
```

### Link with relative path

Alternatively, use relative paths with `file:` protocol:

```json theme={null}
{
  "dependencies": {
    "my-utils": "file:../my-utils"
  }
}
```

## Binaries

If a linked package has a `bin` field, the binary is linked to the global bin directory:

```json theme={null}
{
  "name": "my-cli",
  "bin": {
    "my-cli": "./cli.js"
  }
}
```

After `bun link`, the `my-cli` command is available globally:

```bash theme={null}
$ bun link
$ my-cli --version
1.0.0
```

## Flags

### `--cwd <path>`

Run command in specified directory.

```bash theme={null}
bun link --cwd ~/projects/my-library
```

### `--global-dir <path>`

Use a custom global directory.

```bash theme={null}
bun link --global-dir /custom/path
```

## Unlinking packages

To remove a global link:

```bash theme={null}
cd ~/projects/my-library
bun unlink
```

To remove a linked package from a project:

```bash theme={null}
cd ~/projects/my-app
bun remove my-utils
```

See [bun unlink](/cli/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:

```bash theme={null}
# 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:

```bash theme={null}
# 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](/install/workspaces) instead of `bun link`.

### Testing unpublished packages

Test a package before publishing:

```bash theme={null}
cd ~/projects/new-package
bun link

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