Node.js Reference ยท Module Systems
Node.js module resolution algorithm
How Node.js turns a require() or import specifier into a file: built-ins, relative paths, node_modules lookup, extensions, index files and the differences between CJS and ESM.
Every require('x') and import 'x' starts with a specifier, a string. Module resolution is the process that turns it into the one file that Node.js will load. The rules are different for CommonJS and for ES modules, and understanding them explains most "Cannot find module" errors.
In short: a specifier is either a built-in (node:fs), a path (starts with ./, ../ or /), a # import (see package.json imports), or a bare name such as express or lodash/fp, which is looked up in node_modules folders.
require.resolve('./util'); // CommonJS: a path with guessed extension import.meta.resolve('./util.js'); // ESM: the full file URL, no guessing
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.
How it works
1. Built-in modules
A name that matches a core module (fs, node:fs, node:test) is returned immediately, before any file lookup. Some modules exist only with the node: prefix. A built-in always wins over a package with the same name, so a package called fs in node_modules is never loaded by require('fs').
2. Relative and absolute paths
For CommonJS, Node.js tries the exact file, then adds .js, .json and .node, then looks for a directory with a package.json main field, then for index.js, index.json and index.node. For ES modules the specifier must be the full file name with extension, and a directory is not accepted (ERR_UNSUPPORTED_DIR_IMPORT). A missing file gives ERR_MODULE_NOT_FOUND in ESM and MODULE_NOT_FOUND in CommonJS.
3. Bare names and node_modules
For require('colors') from /a/b/c/file.js, Node.js checks /a/b/c/node_modules/colors, then /a/b/node_modules/colors, then /a/node_modules/colors, then /node_modules/colors, and finally the global folders listed in NODE_PATH, $HOME/.node_modules and $PREFIX/lib/node. The first match wins. When it finds a package folder it reads package.json: the exports field if present (see package.json exports), else main, else index.js.
4. Differences between CommonJS and ESM
CommonJS require() |
ES module import |
|
|---|---|---|
| Extension guessing | Yes (.js, .json, .node) |
No |
Directory index |
Yes | No |
exports of a package |
Honored | Honored |
| Relative to | The requiring file | The importing file's URL |
| Result of a lookup | A path | A file: URL |
| Cache | require.cache by file path |
Module map by URL |
| Symlinks | Resolved to real paths by default | Resolved to real paths by default |
Usage notes
- Use the tools.
require.resolve()andimport.meta.resolve()show what a specifier turns into without running the file. Printing these values is the quickest way to debug a lookup. ERR_MODULE_NOT_FOUNDoften just means a missing extension in ESM: write./util.js, not./util.exportshides files. Once a package hasexports, any path not listed throwsERR_PACKAGE_PATH_NOT_EXPORTED, even if the file exists.- Case matters on Linux, not on default Windows or macOS volumes. A require that works on a laptop can fail in a container.
- Symlinks: a package linked with
npm linkor a workspace is resolved from its real location, so its own dependencies are searched from there.--preserve-symlinkschanges this. - TypeScript with
moduleResolution: "nodenext"follows the same rules, which is why imports there must include.jsextensions. - Speed. Resolution results are cached, but a deep tree of
node_modulesfolders means several failed file-system checks per bare import.