Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js NODE_PATH environment variable

Reference for NODE_PATH: how CommonJS require() searches extra directories, why ES modules ignore it, path separators, and better alternatives.

NODE_PATH is a list of extra directories that Node searches when a bare require('name') cannot be resolved the usual way. The usual way is to look in node_modules folders, starting next to the requiring file and walking up through every parent directory. Directories from NODE_PATH are tried after that walk fails.

It is a legacy mechanism from the time before node_modules lookup was the universal convention. You will meet it in old build setups, shared global module folders and some containers. For new code, prefer a real package, a workspace, package.json imports, or relative paths.

NODE
// shell: NODE_PATH=/opt/shared-modules node app.cjs

Try it

Node.js Resolving a module from NODE_PATH

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js ES modules ignore it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
// POSIX:    NODE_PATH=/dir/one:/dir/two
// Windows:  set NODE_PATH=C:\dir\one;C:\dir\two
Part Description
Value Absolute directory paths separated by : on POSIX or ; on Windows (path.delimiter).
Lookup Each directory is searched as if it were a node_modules folder: NODE_PATH/name must be a package or file.
Order Normal node_modules lookup first, then NODE_PATH entries in order, then the legacy per-user folders ($HOME/.node_modules, $HOME/.node_libraries) and the Node prefix lib/node folder.

Errors: when nothing matches, require() throws an error with code MODULE_NOT_FOUND.

Usage notes

  • CommonJS only. import statements and import() in ES modules never read NODE_PATH. ESM resolution uses URLs, node_modules lookup and package.json fields only. An import 'name' that works under CommonJS can therefore fail after you convert a file to ESM.
  • Not a security boundary and not hermetic. Two machines with different NODE_PATH values resolve the same code differently. That makes builds hard to reproduce, which is the main reason to avoid it.
  • Relative paths in the variable are resolved against the working directory, so they change meaning with cd. Use absolute paths.
  • Bundlers and TypeScript ignore it. Editors, type checkers and bundlers use their own resolution rules, so code can run in Node but show errors in the editor.
  • Alternatives: workspaces and linked packages (npm link, npm install ../shared), the imports field ("#shared/*"), or relative imports. A node_modules folder in a common ancestor directory is also found by the normal upward walk.
  • Global folders. If you installed packages with npm install -g, they live outside the lookup path on purpose; NODE_PATH is a blunt way to expose them and usually a sign that the package should be a local dependency.