Skip to main content

​
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

pm unlink my-library
Output
Running: pnpm unlink my-library
This removes the symbolic link and restores the package from the registry. In the project with linked packages: 
pm unlink
Output
Running: pnpm unlink
In the package that was globally linked: 
cd ~/projects/my-library
pm unlink
Output
Running: pnpm unlink

​
Use Cases

​
After Local Development

When you’re done developing locally:
1

Unlink Package

Remove the symbolic link:
cd ~/projects/my-app
pm unlink my-library
2

Reinstall from Registry

Install the published version:
pm install
3

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
Always unlink packages before deploying to production to avoid missing dependencies.

​
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:
  1. Detects your package manager
  2. Passes all arguments to the native unlink command
  3. Removes symbolic links from node_modules

​
Package Manager Behavior

# Unlink specific package
pnpm unlink my-package

# Remove global link
pnpm unlink --global

​
Verification

Check if package is still linked: 
pm ls my-package
Output (linked)
[email protected]
└── [email protected] -> /Users/you/projects/my-package
Output (unlinked)
[email protected]
└── [email protected]
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

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

# Should return nothing if no links exist

​
Troubleshooting

​
Package Still Linked

If unlink doesn’t work:
  1. Manual removal: 
    rm -rf node_modules/my-package
pm install
  2. Clean reinstall: 
    rm -rf node_modules
pm install

# 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
If you’re working in a monorepo, workspace features handle linking automatically - you don’t need manual link/unlink.
  • pm link - Create symbolic links
  • pm ls - List dependencies and check for links
  • pm install - Reinstall packages from registry