How to Fix npm install Errors

Most npm install failures are one of six errors, and each one names itself in capitals near the top of the output: ERESOLVE, EACCES, ENOENT, EINTEGRITY, a node-gyp build failure, or a network error. Find the code, and the fix follows. The fixes that go round the problem — --force, sudo, deleting the lockfile — each create a worse problem later, so this article gives the direct fix for each and says when the blunt tools are genuinely appropriate.

Step 1: find the code#

Scroll up. The final lines say to look at a log file, which is rarely necessary; the useful part is above, where a line starts with npm error code or npm ERR! code. That code is the section to read below. Also check which Node and npm you are on, since several errors are version-specific:

node --version
npm --version

ERESOLVE: unable to resolve dependency tree#

npm error code ERESOLVE
npm error While resolving: my-app@1.0.0
npm error Found: react@19.1.0
npm error Could not resolve dependency:
npm error peer react@"^18.0.0" from some-library@4.2.0

A package you depend on declares that it needs a different major version of something you already have. Read the two lines: what was found, and what a package wanted. Then:

1. Check whether a newer version of the complaining package supports your version: npm view some-library peerDependencies. Usually it does, and updating it is the fix.
2. If not, and you cannot downgrade the other package, decide whether the mismatch is real. A library declaring React 18 usually works on 19, but not always.

npm install --legacy-peer-deps

This installs anyway, ignoring peer conflicts, which is how npm 6 always behaved. It is acceptable when you have checked the mismatch is harmless. --force is a step further and overrides more; prefer legacy-peer-deps. Either way, put the decision in .npmrc so teammates and CI behave the same, rather than each person rediscovering the flag:

legacy-peer-deps=true

EACCES: permission denied#

npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/some-tool

A global install into a directory owned by root. The fix everyone reaches for, sudo npm install -g, works once and then leaves root-owned files in your cache and global directory, so the next install fails the same way. The correct fix is a global directory you own:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc     # or ~/.zshrc
source ~/.bashrc
npm install -g some-tool

Better still, install Node with a version manager — nvm, fnm or Volta — which puts everything under your home directory from the start. If sudo has already been used and the cache is damaged:

sudo chown -R $(whoami) ~/.npm

For a local project, EACCES means the project folder or node_modules is owned by another user, often after copying from elsewhere or running as root once. Same chown on the project folder.

ENOENT: no such file or directory#

Usually one of two things: there is no package.json in the current folder (you are in the wrong directory), or a path inside a dependency is too long or contains characters the file system rejects, which is mostly a Windows problem. Check pwd first. On Windows, enable long paths or move the project nearer the drive root.

EINTEGRITY: checksum mismatch#

The downloaded package does not match the hash in package-lock.json. Either the cache is corrupt or the lockfile is stale:

npm cache clean --force
npm install

If it persists, the lockfile entry is wrong — typically after a bad merge. Delete only that package’s entry, or regenerate the lockfile as a last resort.

node-gyp: build failures#

npm error gyp ERR! find Python
npm error gyp ERR! stack Error: Could not find any Visual Studio installation to use
npm error make: g++: command not found

A package contains native C++ code and no prebuilt binary exists for your Node version and platform, so npm tries to compile it. That needs Python and a C++ toolchain.

• Windows: install the Visual Studio Build Tools with the C++ workload, and Python. Restart the terminal.
• macOS: xcode-select --install.
• Linux: sudo apt install build-essential python3.

Before installing a compiler, check whether the real cause is a Node version too new for the package. Native packages publish binaries per Node major version; the first weeks after a Node release are when this bites. Switching to the current LTS with your version manager often resolves it with no toolchain at all.

Network errors#

npm error code ETIMEDOUT / ECONNRESET / ENOTFOUND / E407

The registry is unreachable: a proxy, a VPN, a corporate firewall, or an outage. Check the registry setting and any proxy:

npm config get registry          # should be https://registry.npmjs.org/
npm config get proxy
npm config get https-proxy

A leftover registry setting pointing at a company mirror you no longer have access to is a common cause after changing jobs. Reset it with npm config delete registry. Behind a real proxy, set proxy and https-proxy to it.

The clean reinstall#

rm -rf node_modules
npm ci                 # installs exactly what package-lock.json says

This is the right move when node_modules is in a confused state: partial installs, switched branches, a Node version change. npm ci is strict and reproducible. Deleting package-lock.json as well is a different, larger action: it resolves every dependency afresh and can change versions across the whole tree. Do that only when the lockfile itself is the problem, and commit the result deliberately.

Where to go next#

• “require is not defined” — the most common error after a successful install.
• “command not found” but the file exists — for global tools that installed but will not run.
• Git and GitHub explained — why the lockfile belongs in version control.