Cannot find module (Node.js) : les causes et leur correction

L’erreur Cannot find module signifie que Node.js ne trouve pas le fichier ou le paquet demandé par require() ou import. Si le nom commence par ./ ou ../, c’est un fichier local : vérifiez le chemin, l’extension et la casse. Sinon, c’est un paquet absent de node_modules : installez-le avec npm install nom-du-paquet.

Vous tentez de lancer votre projet Node.js sur votre machine et boum, vous vous retrouvez face à la très classique erreur Cannot find module ! Heureusement, vous pouvez résoudre cela en moins de 2 minutes dans la plupart des cas. Voici les causes, de la plus fréquente à la plus discrète.

Mise à jour du 5 octobre 2026 : j’ai ajouté les causes qui ne concernent pas les paquets npm (fichier local, casse, import contre require, module global, main et exports) et un tableau récapitulatif en fin d’article.

Que signifie l’erreur Cannot find module ?

Elle signifie que Node a cherché un module aux endroits prévus par ses règles de résolution et n’a rien trouvé. Le message donne le nom demandé, puis la liste Require stack qui indique quel fichier a déclenché la recherche. C’est votre point de départ :

Error: Cannot find module 'basic-ftp'
Require stack:
- /home/vous/projet/index.js
    at Module._resolveFilename (node:internal/modules/cjs/loader...)
    ... {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/home/vous/projet/index.js' ]
}

Avec la syntaxe import (modules ES), le message change : Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'nom' imported from ... pour un paquet, ou Cannot find module '/chemin/fichier' imported from ... pour un fichier. La cause est la même famille, mais les règles diffèrent (voir plus bas).

Deux règles à connaître :

• Un nom nu (basic-ftp) est cherché dans le dossier node_modules du fichier qui l’appelle, puis dans ceux des dossiers parents.
• Un chemin relatif (./outils, ../lib/outils) est calculé à partir du fichier qui contient le require, et non à partir du dossier où vous avez lancé la commande.

Pour savoir où Node cherche, depuis le dossier du projet :

node -e "console.log(require.resolve('basic-ftp'))"
node -e "console.log(require.resolve.paths('basic-ftp'))"
npm ls basic-ftp

La première commande affiche le chemin du module trouvé, ou lève la même erreur. La deuxième liste les dossiers parcourus. La troisième dit si npm connaît le paquet dans votre projet.

Le module est un paquet npm : que faire ?

Pour notre exemple, définissons que le module manquant est basic-ftp.

L’erreur « Cannot find module ‘basic-ftp' » signifie que le module basic-ftp n’est pas installé dans votre projet Node.js. Pour résoudre cette erreur, installez le module en suivant les étapes ci-dessous :

Étape 1 : Ouvrez un terminal ou une invite de commande et accédez au répertoire de votre projet.

Étape 2 : Installez le module basic-ftp en exécutant la commande suivante :

npm install basic-ftp

Cela installera le module basic-ftp et l’ajoutera comme une dépendance dans votre fichier package.json.

Une fois l’installation terminée, vous devriez être en mesure d’importer et d’utiliser le module basic-ftp dans votre projet sans rencontrer l’erreur « Cannot find module ‘basic-ftp' ».

Étape 3 (optionnel) : Si vous rencontrez toujours des problèmes après avoir suivi ces étapes, vérifiez que le module basic-ftp est correctement répertorié dans les dépendances de votre fichier package.json et que le dossier node_modules contient un sous-dossier nommé basic-ftp avec les fichiers du module. Si ce n’est pas le cas, supprimez le dossier node_modules et réinstallez les dépendances en exécutant npm install.

Avez-vous lancé npm install dans le bon dossier ?

Le dossier node_modules doit se trouver dans le projet, à côté de package.json (ou dans un dossier parent). Si vous avez tapé la commande ailleurs, le paquet est installé au mauvais endroit. Placez-vous à la racine du projet et recommencez.

Le paquet est-il manquant seulement en production ?

Si le paquet figure dans devDependencies, il n’est pas installé quand vous exécutez npm install --omit=dev (ou npm install --production avec les anciennes versions de npm), ce que font souvent les serveurs et les images Docker. Si votre code en a besoin pour tourner, déplacez-le dans dependencies :

npm install --save-prod basic-ftp

Le module est un fichier local (./ ou ../) : que vérifier ?

Si le nom commence par ./ ou ../, ne lancez pas npm install : le fichier est dans votre projet, et Node ne le trouve pas. Vérifiez dans cet ordre.

1. Le chemin. Il part du fichier qui écrit le require. Depuis src/index.js, require('./lib/outils') cherche src/lib/outils. Un ../ en trop ou en moins suffit à provoquer l’erreur.
2. L’extension. Avec require('./outils'), Node essaie outils.js, outils.json puis outils.node, ensuite un dossier outils/ contenant un index.js. Pour tout autre type de fichier (.cjs par exemple), écrivez l’extension en entier.
3. L’existence réelle du fichier. Listez le dossier avec ls (ou dir sous Windows). Un fichier ignoré par git, un dossier dist jamais généré (lancez le build) ou un fichier non copié sur le serveur donnent la même erreur.
4. Le point d’entrée lui-même. Si le chemin dans le message est celui du fichier que vous lancez (Cannot find module '/home/vous/app.js'), vous n’êtes pas dans le bon dossier : déplacez-vous avec cd ou donnez le chemin complet.

Pourquoi ça marche sur Mac et pas sur le serveur Linux ?

Parce que la casse du nom de fichier compte sous Linux, pas par défaut sous macOS ni sous Windows. Un fichier Outils.js chargé avec require('./outils') fonctionne sur votre poste, puis échoue sur un serveur Linux, dans un conteneur Docker ou dans l’intégration continue.

Écrivez le chemin exactement comme le nom réel du fichier, dossiers compris. Si vous renommez un fichier uniquement pour changer sa casse, passez par git pour que le changement soit bien enregistré :

git mv outils.js Outils.js

Pourquoi l’erreur apparaît avec import et pas avec require ?

Parce que require complète les extensions et les dossiers à votre place, alors que import en modules ES ne le fait pas. Un import './outils' sans extension échoue avec ERR_MODULE_NOT_FOUND là où require('./outils') passait.

// CommonJS : l'extension est facultative
const outils = require('./outils')

// Modules ES : l'extension est obligatoire pour un chemin relatif
import outils from './outils.js'

Trois points à vérifier :

• L’extension : ajoutez .js (ou l’extension réelle) à chaque import relatif. Quand le fichier existe avec une extension, Node l’indique souvent à la fin du message (« Did you mean to import … ? »).
• Le dossier : import './lib' ne charge pas lib/index.js (Node répond alors ERR_UNSUPPORTED_DIR_IMPORT). Écrivez ./lib/index.js.
• Le champ type du package.json : avec "type": "module", vos fichiers .js sont traités comme des modules ES. Sans ce champ, ils sont en CommonJS. Les extensions .mjs (modules ES) et .cjs (CommonJS) fixent le mode quel que soit ce champ. Dans un module ES, require n’existe pas.

En TypeScript avec une configuration de type NodeNext, le même principe s’applique : écrivez ./outils.js dans l’import, même si le fichier source s’appelle outils.ts.

Le paquet est installé globalement : pourquoi Node ne le trouve pas ?

Parce que npm install -g sert à installer des outils en ligne de commande, pas des bibliothèques que votre code charge. Le paquet global vit dans un dossier à part (npm root -g donne son emplacement) que require et import ne parcourent pas.

Installez-le dans le projet, sans l’option -g :

npm install basic-ftp

Node sait aussi lire des dossiers globaux via la variable NODE_PATH, mais sa documentation recommande fortement de placer les dépendances dans le dossier local, et cette variable est ignorée par import : gardez les dépendances dans le node_modules du projet.

node_modules ou package-lock.json corrompus : comment repartir de zéro ?

Supprimez node_modules puis réinstallez. Une installation interrompue, un changement de branche ou un dossier copié depuis une autre machine peuvent laisser des paquets incomplets.

rm -rf node_modules
npm install

Sous Windows (invite de commande), la première ligne devient rmdir /s /q node_modules. Pour réinstaller exactement les versions figées dans package-lock.json, utilisez plutôt npm ci : il vide node_modules avant d’installer et s’arrête si le verrou et le package.json ne concordent pas.

Si l’erreur persiste, supprimez aussi package-lock.json avant npm install. Les dépendances sont alors recalculées, donc leurs versions peuvent changer : relisez le résultat avant de le conserver.

Le champ main ou exports du package.json pose problème : comment le repérer ?

Le champ main d’un paquet désigne le fichier chargé quand on écrit require('paquet') (par défaut index.js). S’il pointe vers un fichier qui n’existe pas, souvent un dossier dist qui n’a pas été compilé, Node répond :

Error: Cannot find module '/home/vous/projet/node_modules/paquet/dist/index.js'. Please verify that the package.json has a valid "main" entry

Si le paquet est le vôtre, lancez le build ou corrigez main. S’il vient de npm, réinstallez-le (npm install paquet@latest) ou signalez le problème à son auteur.

Le champ exports, lui, limite les chemins accessibles : dès qu’il existe, seuls les chemins qu’il déclare peuvent être importés. Demander un fichier interne non déclaré (require('paquet/lib/interne')) produit plutôt l’erreur ERR_PACKAGE_PATH_NOT_EXPORTED. Utilisez alors les chemins documentés par le paquet.

En résumé : quelle cause pour quel message ?

Ce que vous voyez	Cause probable	Correction
Cannot find module 'basic-ftp'	Paquet npm non installé	npm install basic-ftp
Cannot find module './outils'	Chemin, extension ou casse du fichier local	Corriger le chemin relatif et le nom exact
ERR_MODULE_NOT_FOUND ... imported from	Import ES sans extension	Ajouter .js à l’import
Marche sur Mac, échoue sur Linux	Casse du nom de fichier	Écrire le nom exact (git mv pour renommer)
Paquet installé avec -g, introuvable	Installation globale	Installer dans le projet, sans -g
Erreur après une installation interrompue	node_modules incomplet	Supprimer node_modules, puis npm install ou npm ci
Please verify that the package.json has a valid "main" entry	Champ main vers un fichier absent	Compiler le paquet, le réinstaller ou corriger main