Comment supprimer node_modules sur Mac sans perdre votre projet

Distinguer node_modules du projet et du cache npm

node_modules est l’arbre de dépendances installé dans un projet : il peut être reconstruit dans de bonnes conditions, mais le projet ne s’exécute ni ne se compile tant que la réinstallation n’est pas terminée. package.json, fichiers de verrouillage (lockfiles), code source, configuration, correctifs, fichiers de workspace et historique Git sont nécessaires à cette reconstruction et ne doivent jamais être supprimés. Le cache de téléchargement partagé de npm, généralement sous ~/.npm, relève encore d’une autre catégorie.

Vérifier que les dépendances peuvent réellement être réinstallées

Un lockfile rend la résolution prévisible, mais ne sauvegarde pas les paquets. Confirmez le gestionnaire et sa version, les accès aux registres privés, au VPN, aux dépendances Git et file:, aux workspaces locaux, aux téléchargements externes et aux outils nécessaires à la compilation des modules natifs. npm v12 ne lit plus npm-shrinkwrap.json : si un ancien projet ne contient que ce fichier au même format, renommez-le en package-lock.json avant d’utiliser npm v12. N’écrasez jamais un package-lock.json existant ; comparez et réconciliez les deux fichiers séparément. Toute modification faite uniquement dans node_modules disparaîtra.

1. À la racine du projet, exécutez pwd et du -sh ./node_modules, puis notez aussi l’espace libre de macOS.
2. Vérifiez package.json, le bon lockfile, la configuration du workspace et les changements locaux ; avec npm v12, renommez npm-shrinkwrap.json en package-lock.json seulement si ce dernier n’existe pas déjà.
3. Confirmez l’accès aux registres privés, dépendances Git et file:, paquets locaux, téléchargements externes et outils de build, puis arrêtez les processus qui utilisent node_modules.
4. Placez uniquement le dossier node_modules vérifié dans la Corbeille et réinstallez depuis la bonne racine, avec le gestionnaire et le lockfile prévus par le dépôt.
5. Exécutez build, tests, lint et démarrage, mesurez de nouveau l’espace, puis ne videz la Corbeille qu’une fois tout validé.

N’utilisez jamais node_modules comme unique copie d’un paquet ou d’une correction manuelle. Si une dépendance exacte n’est plus accessible et n’a été archivée nulle part, sa suppression peut rendre un ancien projet inutilisable.

Retirer un seul dossier de dépendances vérifié

Depuis la racine du dépôt, après l’avoir vérifiée, placez uniquement node_modules dans la Corbeille du Finder, jamais le dépôt parent. Dans le Terminal, rm -rf ./node_modules contourne la Corbeille et reste irréversible : vérifiez d’abord la racine avec pwd. Réinstallez ensuite avec npm ci si package-lock.json fait autorité, ou avec la commande qui interdit toute modification du lockfile pour le gestionnaire du dépôt (par exemple pnpm install --frozen-lockfile, yarn install --immutable ou bun install --frozen-lockfile). Dans un monorepo, partez du lockfile racine et traitez les workspaces comme un seul système de dépendances.

Réinstaller puis valider tout le projet

Une installation réussie ne prouve pas encore que le projet est restauré. Exécutez les builds, tests, contrôles lint et commandes de démarrage documentés ; les modules natifs et les scripts de cycle de vie peuvent encore échouer après un changement d’outils. La restauration demande des téléchargements, de la décompression, la recréation de liens et parfois une compilation. En cas d’échec, restaurez le dossier depuis la Corbeille et diagnostiquez les accès, le réseau, les versions et le lockfile avant de nettoyer un autre projet.

Limites de suppression et coût de récupération

Repérez les gros dossiers node_modules sur Mac, protégez le code source et le lockfile, puis réinstallez les dépendances avec npm, pnpm, Yarn ou Bun.

FAQ