Erreurs npm install : Chaque erreur courante et comment la corriger

Lancer npm install et se heurter a un mur de texte rouge est un rite de passage pour tout developpeur JavaScript. Que ce soit une erreur de permissions sur macOS, un conflit de dependances dans un monorepo ou un cache corrompu en CI, la solution est generalement simple une fois que vous savez quoi chercher. Ce guide couvre chaque erreur courante de npm install, explique pourquoi elle survient et vous donne les commandes exactes pour la corriger.

Dictionnaire des erreurs : tableau de reference rapide

EACCES : corriger les erreurs de permissions

C'est l'erreur la plus courante sur macOS et Linux. Elle se produit quand npm tente d'installer des packages globaux dans un repertoire systeme comme /usr/local/lib/node_modules.

Correction sur macOS / Linux (recommande : utiliser nvm)

La meilleure correction permanente est d'utiliser un gestionnaire de versions Node pour que npm installe dans votre repertoire personnel :

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal, then install Node
nvm install --lts
nvm use --lts

# Verify — npm now installs to ~/.nvm/
which npm
# /home/youruser/.nvm/versions/node/v20.x.x/bin/npm

Alternative : changer manuellement le repertoire par defaut de npm :

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to ~/.bashrc or ~/.zshrc:
export PATH=~/.npm-global/bin:$PATH

# Reload shell
source ~/.bashrc

Option nucleaire (deconseille pour la plupart des utilisateurs) :

# NOT recommended — changes system directory ownership
sudo chown -R $(whoami) /usr/local/lib/node_modules
sudo chown -R $(whoami) /usr/local/bin
sudo chown -R $(whoami) /usr/local/share

Correction sur Windows

Sous Windows, lancez votre terminal en tant qu'administrateur, ou mieux, utilisez nvm-windows :

# Install nvm-windows from:
# https://github.com/coreybutler/nvm-windows/releases

# Then in an elevated (Admin) PowerShell:
nvm install lts
nvm use lts

# Or fix npm prefix for current user:
npm config set prefix %APPDATA%\npm

ERESOLVE : corriger les conflits de dependances

Depuis npm 7, les conflits de peer dependencies font echouer l'installation par defaut. Vous verrez un diagramme en arbre montrant les packages en conflit.

Sortie d'erreur typique :

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: @some-org/some-package@2.1.0
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   react@"^18.2.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0 || ^17.0.0" from some-library@3.5.0
npm ERR! node_modules/some-library
npm ERR!   some-library@"^3.5.0" from the root project

--legacy-peer-deps vs --force

--legacy-peer-deps dit a npm d'ignorer completement les conflits de peer dependencies (meme comportement que npm 6). --force dit a npm d'installer quand meme. Quand utiliser chacun :

# Option 1: Ignore peer deps (safest workaround)
npm install --legacy-peer-deps

# Option 2: Force install (overrides everything)
npm install --force

Approche preferee — epingler la dependance en conflit :

// In package.json — add "overrides" to pin the conflicting dep
{
  "overrides": {
    "some-library": {
      "react": "^18.2.0"
    }
  }
}

// Then run:
// npm install

Corruption de node_modules : quand et comment supprimer et reinstaller

Parfois node_modules se retrouve dans un etat corrompu. Les symptomes incluent des erreurs "Cannot find module" pour des packages presents dans package.json, ou des echecs de build etranges apres un changement de branche.

Quand supprimer node_modules

• Apres avoir change de branche avec des arbres de dependances differents.
• Apres avoir resolu des conflits de fusion dans package-lock.json.
• Quand "Module not found" apparait pour un package clairement installe.
• Apres une mise a jour de Node.js vers une nouvelle version majeure.

Comment faire une reinstallation propre

Commande multiplateforme (bash) :

rm -rf node_modules package-lock.json
npm install

Sous Windows (PowerShell) :

Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

Avec npx :

npx rimraf node_modules
npm install

Si les problemes persistent, nettoyez aussi le cache npm :

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Conflits package-lock.json : strategies de fusion

Quand plusieurs developpeurs modifient les dependances, les conflits de fusion de package-lock.json sont quasi garantis. N'essayez jamais de les resoudre manuellement — le fichier est genere automatiquement.

Strategie de fusion recommandee

Accepter l'un ou l'autre cote du conflit (peu importe lequel) :

# Accept "theirs" (the incoming branch's version)
git checkout --theirs package-lock.json
git add package-lock.json

# OR accept "ours" (your branch's version)
git checkout --ours package-lock.json
git add package-lock.json

Regenerer le fichier de verrouillage :

npm install

Commiter le resultat :

git add package-lock.json
git commit -m "chore: regenerate package-lock.json after merge"

Prevenir les conflits avec .gitattributes

Ajoutez ceci a votre .gitattributes pour resoudre automatiquement les conflits du fichier de verrouillage :

# .gitattributes
package-lock.json merge=ours

Incompatibilite de version Node.js

Beaucoup de packages necessitent des versions specifiques de Node.js. Si votre version est trop ancienne (ou trop recente), npm install peut echouer avec des erreurs de compilation.

Verifier la version requise

Cherchez le champ engines dans package.json :

// package.json
{
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  }
}

// Check your current version:
// node -v
// npm -v

Utiliser nvm ou fnm pour changer de version

nvm (Node Version Manager) :

# List available versions
nvm ls-remote

# Install a specific version
nvm install 20

# Switch to a version
nvm use 20

# Set a default
nvm alias default 20

fnm (Fast Node Manager) — alternative plus rapide :

# Install fnm (Rust-based, faster than nvm)
curl -fsSL https://fnm.vercel.app/install | bash

# Install and use a version
fnm install 20
fnm use 20
fnm default 20

Creez un fichier .nvmrc a la racine du projet pour que toute l'equipe utilise la meme version :

# Create .nvmrc file
echo "20" > .nvmrc

# Team members just run:
nvm use
# or
fnm use

Problemes CI/CD : builds Docker et GitHub Actions

npm install se comporte differemment dans les environnements CI. Le cache, les permissions et les parametres reseau necessitent une attention particuliere.

Builds Docker

Erreurs courantes dans les Dockerfiles :

# BAD Dockerfile — no layer caching, uses npm install
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "index.js"]

# GOOD Dockerfile — proper layer caching, uses npm ci
FROM node:20-alpine
WORKDIR /app

# Copy package files first (layer caching!)
COPY package.json package-lock.json ./

# Use npm ci for deterministic installs
RUN npm ci --ignore-scripts

# Then copy the rest of the source
COPY . .

# Run any build steps after copy
RUN npm run build

CMD ["node", "index.js"]

Points cles : copier d'abord les fichiers package pour le cache de couches, utiliser npm ci au lieu de npm install en CI (plus rapide et deterministe), utiliser --ignore-scripts si les scripts postinstall ne sont pas necessaires.

Cache GitHub Actions

Un cache correct peut reduire le temps d'installation de plus de 70% :

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'  # Caches ~/.npm automatically

      - run: npm ci       # Deterministic install
      - run: npm test
      - run: npm run build

Organigramme de decision : npm install a echoue — suivez ce guide

Utilisez cet organigramme pour diagnostiquer votre echec npm install :

Questions frequemment posees