Where does npm read its config? Four files plus environment variables

npm reads settings from four files: the project .npmrc, the per-user ~/.npmrc, the global config at the prefix, and npm's built-in file. On top of that, any environment variable that starts with npm_config_ becomes a config parameter. A registry or token setting can come from any of the five.

The four files

The npm documentation lists them in this order:

All of them are ini-formatted lists of key and value pairs. The docs add that environment variables can be substituted inside a file using the dollar and braces form, which is how teams keep tokens out of committed files.

The environment variable route

The config documentation states that any environment variable beginning with npm_config_ is read as a configuration parameter. Putting npm_config_foo set to bar in your environment sets the foo parameter to bar. Names are case insensitive. Variables with no value are treated as true.

So a registry setting can arrive from a place that is not a file at all.

Why you should know this

When npm behaves unexpectedly, such as fetching from an unexpected registry or failing to authenticate, the cause is often one of the layers you forgot. A project file can be committed by a teammate. A user file can hold a token from last year. A variable can be exported by a profile script.

It is also a security point. A project level .npmrc travels with a repository, so cloning code means accepting its npm settings when you run npm there. Our post on CLIs that trust config inside a repo explains the pattern, and scoped registries and token scoping shows how to keep tokens narrow.

A short audit

npm config list
npm config list -l
env | grep -i '^npm_config_'

The first command shows settings that differ from defaults along with where each came from. The second shows everything. The third prints variables from your session.

Then open the project .npmrc in any repository you are about to run install in, particularly one you just cloned.

Habits that help

1. Never commit a literal token. Use the variable substitution form and set the value in the environment or a secrets manager.
2. Keep the per-user file small and review it when you leave a project.
3. Treat a new .npmrc in a pull request as a security relevant change.
4. Print the resolved config at the start of CI jobs.
5. Remove old tokens from your laptop when a project ends.

For the pip equivalent, see environment variables and pip.

Quick check

Sources

• npmrc documentation
• npm config documentation

Last reviewed: 19 October 2026.