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

Terminal

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.

Terminal

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

Using this in CI

Node tooling on a runner differs from your machine in three ways that matter: CI=true is set, there is no TTY, and the Node major may not be the one you develop on.

Pin the Node major with setup-node and in engines. Native modules resolve different prebuilt binaries per major.
CI=true changes behaviour in several tools, most often by promoting warnings to errors or disabling interactive prompts.
Commands that expect a TTY will hang. Pass the non-interactive or --yes flag explicitly.
Use npm exec or node_modules/.bin rather than assuming a globally installed binary is on PATH.

Frequently asked questions

npm unlink: Usage & Common Errors?

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?

Common gotcha: package missing after unlink?