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.
// shell: NODE_PATH=/opt/shared-modules node app.cjs
Try 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.
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
// 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.
importstatements andimport()in ES modules never readNODE_PATH. ESM resolution uses URLs,node_moduleslookup andpackage.jsonfields only. Animport '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_PATHvalues 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), theimportsfield ("#shared/*"), or relative imports. Anode_modulesfolder 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_PATHis a blunt way to expose them and usually a sign that the package should be a local dependency.