npm unlink: Usage & Common Errors

By Daniel Zoghalchali·Latchkey

Remove a symlink created by npm link.

npm unlink removes a link created by npm link - either the per-project symlink or the global one - so the project goes back to using the registry-installed dependency.

What it does

In a consuming project, npm unlink <name> removes the symlink from node_modules; you then run npm install to restore the real package. Run in the library directory with no args, it removes the global link.

Common usage

npm unlink my-lib && npm install   # restore the real dependency
# in the library, remove the global link:
npm unlink

Common gotcha: package missing after unlink

After npm unlink the project throws "Cannot find module" because unlink only removed the symlink - it did not install the real package. Always follow npm unlink with npm install (or npm ci) to put the registry version back.

npm unlink my-lib
npm install                 # reinstall the real dependency

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation