npm reports EACCES when the operating system denies a requested filesystem operation. On Unix-like systems this often occurs during global installs to a system-owned prefix, but local project errors can instead involve cache or workspace permissions.
This guide is for npm EACCES permission denied in its stated software or device context. Capture the exact message and the operation that fails; the same keyword may have different meanings in another application. A reliable diagnosis identifies an observable difference, not just a plausible cause.
Recognize the symptoms
- `npm install -g` fails writing to `/usr/local` or another protected prefix.
- The same package installs within a project but fails globally.
- Commands once executed with sudo left files owned by root in a developer directory.
Record the software version, device or server role, first failure time and any update or configuration change immediately before the incident. Compare whether the symptom affects one file, one user, one device or the entire service. These observations guide the safest first test.
Before making changes
Keep a restorable copy of important files, settings and credentials wherever the procedure might modify them. Use the original account, workflow and network for comparison. Perform one controlled change at a time, record the outcome, and undo changes that do not affect the failure.
If the action can create payments, data writes, account changes or destructive storage activity, do not retry it automatically. Confirm whether the previous operation already succeeded. Managed devices, production databases and service infrastructure require the owner’s authorization.
Step-by-Step Troubleshooting
Choose Beginner for reversible checks; Advanced covers evidence-based inspection, bounded changes and verification.
Read the denied path and install mode
Record the EACCES action (mkdir, rename or open), the path and whether the command included `-g`. Never treat a permission error as a reason to grant everyone write access.
Inspect Node, npm and global prefix
Run `node -v`, `npm -v` and `npm config get prefix`. This identifies which installation is controlling global package placement.
Prefer a Node version manager
According to npm guidance, install and select Node using a supported version manager for your user account. This normally places global packages under a user-writable directory.
Use a project-local tool when possible
Many CLI tools can run via `npx` or an explicitly declared devDependency instead of global installation. Choose an approved package version and verify its provenance before executing.
Inspect cache and project ownership precisely
Use a read-only listing to identify the exact denied file and owner. If root-owned files exist in a user-controlled project, correct only those files with appropriate authorization; do not recurse across /usr.
node -vnpm -vnpm config get prefixnpm config get cache# Inspect the specific denied path from the error before modifying permissions.Evaluate a user-level npm prefix
npm documents an alternative local prefix such as `~/.local` on Unix-like systems. Ensure PATH includes the selected bin directory and shell startup files are updated consistently.
Separate CI permissions from developer permissions
In containers and CI, identify which user installs dependencies and where cache/home mounts are writable. Avoid running build containers as root solely to silence a permissions error.
Test reproducible installation and rollback
Install a trusted small package into the chosen approved environment, rerun the original operation, and record the prefix/version configuration for future builds.
Diagnosis: identify the layer that is actually failing
Start with the evidence collected by the Beginner or Advanced tab, then compare the patterns below. A match is a working hypothesis; it is not proof until the original operation succeeds after a targeted, reversible change.
| Observed pattern | Evidence to inspect | Most useful next step |
|---|---|---|
| Only global installs fail | npm config get prefix | Prefer version manager or user-writable prefix. |
| Local project install fails | Exact denied path from error message | Fix scoped workspace ownership if confirmed. |
| Problem follows sudo usage | File ownership in the specific affected directory | Correct only authorized user-owned files. |
Common root causes to rule in or out
- Global npm prefix is owned by the OS or administrator.
- Node.js was installed in a system location while the user expects user-level global packages.
- A local npm cache/project directory has incorrect ownership after an elevated run.
A recent change establishes a useful timeline but not causation on its own. Look for a repeatable relationship: does the failure follow a particular account, release, host, storage volume or workload? Compare an unaffected example under nearly identical conditions before choosing any broad repair.
What each result means
When the same problem reproduces on multiple independent devices or clients, focus on shared account, service or infrastructure conditions. When it follows one client, check its runtime, policies and local state. When only one particular operation fails, inspect that workload before reinstalling unrelated components.
If a command or diagnostic produces a different result than the article describes, stop and interpret that actual output. Examples are not meant to be executed blindly: identifiers, installation paths, network ports and supported options can vary by version and permissions.
How to verify the repair
Return to the exact action that produced npm EACCES permission denied. Repeat the safe test under the original account, environment and input conditions. An error disappearing after one reload is not enough if the underlying service still produces failures under normal use.
- Repeat the exact npm command without sudo.
- Confirm npm prefix and installed CLI location.
- Check that unrelated system locations retain original ownership.
Confirm that the adjacent feature still works and that the protective controls, data and settings kept during diagnosis remain intact. Record the exact effective change and keep the rollback instructions; a completed checklist is a tracking aid, not a guarantee that all failure conditions are gone.
Solution Checklist
If the error remains: rollback and escalation
Restore original npm prefix or PATH changes that did not help. Remove only the package installed during testing, not unrelated global tools.
Provide support with the redacted exact message, timestamps and timezone, version, environment, scope, relevant log excerpts and tests attempted. Do not include passwords, session cookies, license keys, complete private URLs or other secrets in public tickets.
How to prevent it from returning
- Use a version manager and project-local dependencies.
- Never mix elevated and non-elevated npm operations.
- Document package manager version and CI user permissions.
Maintain a short incident note that distinguishes the confirmed cause from hypotheses that were tested and rejected. Update the note when a product release or platform policy changes the troubleshooting sequence.
Frequently asked questions
Is chmod 777 an acceptable npm fix?
No. It permits excessive write access and hides the actual installation ownership problem.
Should I use npx instead of a global install?
Often yes for occasional tools, provided the package source/version is trusted and your organization permits execution.
Further reading: official documentation
Editorial note: vendor interfaces, error-code behavior and supported versions may change. Confirm the relevant product documentation before deploying a change to a production or managed system. This draft does not claim that every remedy was tested on the reader’s environment.
Disqus hosts the discussion. Comments load automatically as you approach this section and may use cookies.