@workingmodel/why-wont-this-install

Diagnoses why npm install is failing and tells you in plain English how to fix it. Developed by Working Model.

$ why-wont-this-install

why-wont-this-install — scanning /your/project

✖ ERROR  Engine mismatch
  Your Node version (18.4.0) doesn't satisfy the required range: >=22.0.0
  Fix: Install Node >=22.0.0 via nvm: `nvm install 22`

✖ ERROR  Conflicting lock files
  Multiple lock files found: package-lock.json, yarn.lock
  Fix: Pick one package manager and delete the other lock file(s).

2 errors found.

Install

npx @workingmodel/why-wont-this-install

Or install globally:

npm install -g @workingmodel/why-wont-this-install

Usage

Run from your project directory:

why-wont-this-install

Or point it at a specific path:

why-wont-this-install /path/to/project

What it checks

| Check | What it catches | |---|---| | Engine mismatch | Node or npm version doesn't satisfy engines field | | Conflicting lock files | Multiple package managers have touched the project | | Lock file version | package-lock.json lockfileVersion requires a newer npm | | Wrong package manager hint | yarn.lock or pnpm-lock.yaml present but you're running npm | | Permission error | node_modules is not writable by the current user | | Platform mismatch | Package's os field excludes your operating system | | CPU mismatch | Package's cpu field excludes your architecture | | Custom registry | npm is pointed at a non-default registry | | Corrupted install | node_modules exists but install markers are missing | | No package.json | You're in the wrong directory |

Exits with code 1 if any errors are found — safe to use in CI.

Why This Exists

You've seen it: npm install fails with a wall of red text and the actual reason is buried three screens up. Sometimes it's the wrong Node version. Sometimes it's a lock file from a different package manager. Sometimes it's a permission issue that happened six months ago. This tool scans your project in two seconds and names the culprit.

More tools from Working Model → workingmodel.co · npm @workingmodel