pm unlink

Remove symbolic links between packages

Overview

The pm unlink command removes symbolic links created by pm link, restoring packages to their published versions from the registry.

Syntax

pm unlink [...args]

Arguments

args string[]

Package names or arguments passed to your package manager’s unlink command

Examples

Unlink Specific Package

pm unlink my-library

Running: pnpm unlink my-library

This removes the symbolic link and restores the package from the registry.

Unlink All Packages

In the project with linked packages:

pm unlink

Running: pnpm unlink

Remove Global Link

In the package that was globally linked:

cd ~/projects/my-library
pm unlink

Running: pnpm unlink

Use Cases

After Local Development

When you’re done developing locally:

Unlink Package

Remove the symbolic link:

cd ~/projects/my-app
pm unlink my-library

Reinstall from Registry

Install the published version:

pm install

Verify

Check the package is from registry:

pm ls my-library

Before Deployment

Ensure no development links exist:

# Check for linked packages
pm ls

# Unlink any found
pm unlink my-dev-package

# Clean install
pm install

Switching Development Setup

Switch from linked to published version:

# Unlink local version
pm unlink ui-library

# Install published version
pm add ui-library

How It Works

From src/commands/unlink.ts:10-17:

export const unlinkCmd = cli.Command.make('unlink', { args: argsArg }, (args) =>
  Effect.gen(function* () {
    const pm = yield* PackageManagerService;
    const passthrough = Array.from(args.args);
    const cmd = ShellCommand.make(pm.name, 'unlink', ...passthrough);
    yield* Console.log(`Running: ${pm.name} unlink ${passthrough.join(' ')}`);
    yield* runShellCommand(cmd);
  }).pipe(Effect.provide(PackageManagerLayer)),
);

The command:

Detects your package manager
Passes all arguments to the native unlink command
Removes symbolic links from node_modules

Package Manager Behavior

# Unlink specific package
pnpm unlink my-package

# Remove global link
pnpm unlink --global

# Unlink specific package
bun unlink my-package

# Unlink from current directory
bun unlink

# Unlink specific package
npm unlink my-package

# Remove global link
npm unlink

Verification

Check if package is still linked:

pm ls my-package

my-app@1.0.0
└── my-package@1.0.0 -> /Users/you/projects/my-package

my-app@1.0.0
└── my-package@1.0.0

No -> arrow means it’s installed normally.

Restore Published Version

After unlinking, reinstall from registry:

pm unlink my-library
pm install

Or reinstall specific package:

pm unlink my-library
pm add my-library

Common Workflows

Complete Cleanup

Remove all development links:

# Unlink packages
pm unlink package-a package-b

# Clean node_modules
rm -rf node_modules

# Fresh install
pm install

Switch Between Linked and Published

# Development mode (linked)
pm link my-library

# Production mode (published)
pm unlink my-library
pm install

Verify No Links

# Check for symbolic links
pm ls | grep '->'

# Should return nothing if no links exist

Troubleshooting

Package Still Linked

If unlink doesn’t work:

Manual removal:

rm -rf node_modules/my-package
pm install

Clean reinstall:
```
rm -rf node_modules
pm install
```

Global Link Persists

# List global links
pm ls --global

# Remove global link
cd ~/projects/my-package
pm unlink --global

Module Resolution Issues

After unlinking, you may need to:

# Clear package manager cache
pm cache clean

# Reinstall
pm install

Best Practices

Unlink before commits - Don’t commit with linked packages
Document linked packages - Keep track of what’s linked
Verify after unlink - Check with pm ls that links are removed
Clean install after - Run pm install to restore published versions

pm link - Create symbolic links
pm ls - List dependencies and check for links
pm install - Reinstall packages from registry