npm and pip install errors: what the messages mean

Package installs fail loudly. npm and pip can print dozens of lines, and the last one is often a generic "failed" message. The useful line is usually higher up: the first error, with a code or a short reason. Once you know the handful of common messages, most install failures point clearly at one of four things: permissions, disk space, versions that do not fit together, or the system protecting its own Python.

Read from the first error, not the last

Scroll up to the first line marked as an error. Look for:

• A code in capitals, such as EACCES, ENOSPC, E404 or ENOENT. These are short names for the failure.

• A package name and version, which tells you which dependency caused the trouble.

• A file path, which tells you where npm or pip was trying to write or read.

npm also writes a detailed debug log. Its configuration docs say logs go in a logs folder inside npm's cache directory by default.

Common npm errors

EACCES (permission denied). npm tried to write to a folder your user account cannot change, most often during a global install. npm's documentation recommends reinstalling Node.js and npm with a Node version manager, which it calls the way to avoid permission issues, or changing npm's default directory to one you own. Its fix is aimed at letting you install global packages without sudo.

ENOSPC (no space). npm's common errors page shows it as:

npm ERR! Error: ENOSPC, write

The fix is to free disk space or point npm's temporary folder at a drive with more room.

404 Not Found. npm's documentation says a 404 from the registry is most likely a temporary glitch, so check npm's status page and try again later. Also check the package name for typos and, for private packages, that you are signed in to the right registry.

Peer dependency conflicts. Some packages declare "peer dependencies": other packages they expect you to have in specific versions. When two of these disagree, npm may refuse to install. Its documentation explains that the legacy-peer-deps setting makes npm "completely ignore peerDependencies", as versions 3 through 6 did. That can get an install through, but it skips a safety check, so read which versions conflict first. npm's docs say of the force option: "If you don't have a clear idea of what you want to do, it is strongly recommended that you do not use this option!"

Strange or random errors. npm's own advice is that "some strange issues can be resolved by simply running npm cache clean and trying again", and to rerun the install with the verbose option for more detail.

Common pip errors

Conflicting dependencies (ResolutionImpossible). pip's documentation shows a message like this. Its example uses made-up package names; we have written the version ranges out in words:

ERROR: Cannot install package_coffee==0.44.1 and package_tea==4.3.0 because these package versions have conflicting dependencies.

The conflict is caused by:

package_coffee 0.44.1 depends on package_water (2.4.2 or later, below 3.0.0)

package_tea 4.3.0 depends on package_water==2.3.1

Read the "caused by" lines: two packages need incompatible versions of a third. pip suggests removing requirements you no longer need, loosening version pins so pip has room to find a match, or asking the package maintainers to relax their constraints. Note that the pip team says it cannot provide support for individual dependency conflicts.

Externally managed environment. On some recent Linux distributions and other setups, the system Python is marked as managed by the operating system, and pip refuses to install into it. The Python packaging specification says the error should suggest creating a virtual environment. A flag such as --break-system-packages exists to override it, but it is off by default for a reason: changing system packages can break tools your operating system relies on.

Running the wrong pip. If a package installs but your script cannot find it, you may have several Pythons. The Python Packaging User Guide recommends running pip through Python, for example "python3 -m pip --version" on macOS and Linux or "py -m pip --version" on Windows, which also shows which Python it belongs to.

Using a virtual environment

A virtual environment is a private folder of packages for one project, so installs do not collide with the system or with other projects. The packaging guide's commands, using a folder called tutorial_env:

python3 -m venv tutorial_env

source tutorial_env/bin/activate

On Windows, the guide uses "py -m venv tutorial_env" and then "tutorial_env\Scripts\activate". Once it is active, pip installs go into that folder.

A checklist before you search the error

1. Copy the first error line and the code.

2. Note your Node and npm versions, or Python and pip versions.

3. Note your operating system and whether you used sudo or an administrator prompt.

4. Check whether the same install works in a fresh folder or a new virtual environment.

5. Look for the package's own install notes; some need extra system tools.

If you post the output to a forum or issue tracker, remove tokens, private registry addresses and user names from paths. Our guide on sharing logs safely shows what to look for. If the install worked but the code then fails, our guide to reading a stack trace is the next step.

Have the install output read for you

EasyToDecode is launching soon. You will be able to paste the full npm or pip output and get the line that matters quoted back, a plain-English explanation, the safest thing to try first and the details to include if you need to ask for help. See how it works or join the waitlist to hear when it opens.