Researched guidance: How should module-not-found errors distinguish installation location from module resolution?

Summary

A module-not-found error describes a failed lookup in the failing process's resolution context; it does not by itself prove that a package was never installed. Diagnose the runtime, caller, specifier form, and search paths separately.

Candidate action

First capture the exact failing runtime, entry file, working directory, import/require form, and requested name. For Node CommonJS, classify the request as core, relative, absolute, or bare; run require.resolve(request) from the same caller context and, for a bare name, inspect require.resolve.paths(request). Compare those paths with the effective project root and the package's actual location. For ESM, use ESM-aware resolution and do not assume CommonJS extension, folder, or NODE_PATH rules apply. If the dependency is loaded by a project, install it locally in that project's effective package root; npm documents global installs as command-line tooling, not the normal require() dependency location. For Python, inspect the exact interpreter's sys.path and the relevant package __path__ / finder context, then compare the package location with those search locations; a filesystem copy outside the import path is not evidence of discoverability. Only after the lookup context is aligned should the fix be chosen: correct the working directory/package root, install into the same environment, correct the specifier or package exports, or add an intentional and reproducible path configuration.

Applicability

• Node.js CommonJS applications and CLI jobs that report MODULE_NOT_FOUND.
• Node.js ESM applications where import resolution differs from require resolution.
• Python applications and CI jobs that report ModuleNotFoundError.
• CI, containers, monorepos, and workspaces where install and execution contexts can differ.

Key findings

• Node CommonJS resolution is relative to the real path of the calling module; bare names traverse node_modules locations, while require.resolve returns the filename without loading it and require.resolve.paths exposes the lookup paths. (S1)
• Node ESM import resolution is not interchangeable with CommonJS: it does not use CommonJS extension searching or NODE_PATH, and directory imports require explicit paths. (S2)
• npm's documented default is local installation under the effective package root's node_modules for packages loaded with require(); global installs go under the Node prefix and are intended for command-line use. (S4)
• Python raises ModuleNotFoundError when no import path or meta-path finder supplies a module spec; sys.path, package __path__, sys.meta_path, and path hooks define discoverability for the running interpreter. (S3)

Known limitations

• The official documentation defines resolution and search-path mechanisms but does not provide a universal command that proves a package is installed everywhere on a filesystem.
• Custom Node loader hooks, package-manager link/plug-in layouts, Python import hooks, zip imports, and workspace tooling can change the effective lookup context.
• A successful resolution probe establishes discoverability for that exact runtime, caller, specifier, and environment; it does not prove another process or deployment will resolve the same way.
• Documentation research was not execution or independent reproduction.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false
• The sources establish documented resolution rules and recommended installation placement, not a passing test in the user's environment.

What remains unknown

• Which runtime and package manager produced the target error, and whether the failing request uses CommonJS, ESM, Python imports, or another loader.
• The exact caller file, working directory, interpreter executable, package root, dependency declaration, and search paths in the affected environment.
• Whether the failure is caused by a missing install, a different runtime/environment, a wrong relative or bare specifier, package exports, a custom loader/import hook, or a stale CI/container layer.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 CommonJS modules | Node.js v26.9.0 Documentation · official_documentation · accessed 2026-09-21
• S2 Modules: Packages | Node.js v26.9.0 Documentation · official_documentation · accessed 2026-09-21
• S3 5. The import system — Python 3.14.6 documentation · official_documentation · accessed 2026-09-21
• S4 Folders - npm Docs · official_documentation · accessed 2026-09-21