NPMRC(5) File Formats Manual NPMRC(5)
NAME
npmrc
Description
npm gets its config settings from the command line, environment vari-
ables,
and npmrc files.
The npm config command can be used to update and edit the contents of
the
user and global npmrc files.
For a list of available configuration options, see
config.
Files
The four relevant files are:
• per-project config file (/path/to/my/project/.npmrc)
• per-user config file (~/.npmrc)
• global config file ($PREFIX/etc/npmrc)
• npm builtin config file (/path/to/npm/npmrc)
All npm config files are an ini-formatted list of key = value parame-
ters.
Environment variables can be replaced using ${VARIABLE_NAME}. For
example:
prefix = ${HOME}/.npm-packages
Each of these files is loaded, and config options are resolved in pri-
ority
order. For example, a setting in the userconfig file would override
the
setting in the globalconfig file.
Array values are specified by adding "[]" after the key name. For exam-
ple:
key[] = "first value"
key[] = "second value"
Comments
Lines in .npmrc files are interpreted as comments when they begin with
a
; or # character. .npmrc files are parsed by
npm/ini, which specifies this comment syntax.
For example:
# last modified: 01 Jan 2016
; Set a new registry for a scoped package
@myscope:registry=https://mycustomregistry.example.org
Per-project config file
When working locally in a project, a .npmrc file in the root of the
project (ie, a sibling of node_modules and package.json) will set
config values specific to this project.
Note that this only applies to the root of the project that you're run-
ning
npm in. It has no effect when your module is published. For example,
you
can't publish a module that forces itself to install globally, or in a
different location.
Additionally, this file is not read in global mode, such as when run-
ning
npm install -g.
Per-user config file
$HOME/.npmrc (or the userconfig param, if set in the environment or on
the command line)
Global config file
$PREFIX/etc/npmrc (or the globalconfig param, if set above): This file
is an ini-file formatted list of key = value parameters. Environment
variables can be replaced as above.
Built-in config file
path/to/npm/itself/npmrc
This is an unchangeable "builtin" configuration file that npm keeps
consistent across updates. Set fields in here using the ./configure
script that comes with npm. This is primarily for distribution main-
tainers
to override default configs in a standard and consistent manner.
Auth related configuration
The settings _auth, _authToken, username and _password must all be
scoped to a specific registry. This ensures that npm will never send
credentials to the wrong host.
The full list is:
• _auth (base64 authentication string)
• _authToken (authentication token)
• username
• _password
• email
• certfile (path to certificate file)
• keyfile (path to key file)
In order to scope these values, they must be prefixed by a URI frag-
ment.
If the credential is meant for any request to a registry on a single
host,
the scope may look like //registry.npmjs.org/:. If it must be scoped to
a
specific path on the host that path may also be provided, such as
//my-custom-registry.org/unique/path:.
; bad config
_authToken=MYTOKEN
; good config
@myorg:registry=https://somewhere-else.com/myorg
@another:registry=https://somewhere-else.com/another
//registry.npmjs.org/:_authToken=MYTOKEN
; would apply to both @myorg and @another
; //somewhere-else.com/:_authToken=MYTOKEN
; would apply only to @myorg
//somewhere-else.com/myorg/:_authToken=MYTOKEN1
; would apply only to @another
//somewhere-else.com/another/:_authToken=MYTOKEN2
See also
• npm folders
• npm config
• config
• package.json
• npm
9.2.0 December 2022 NPMRC(5)
Generated by dwww version 1.15 on Tue Sep 2 04:03:32 CEST 2025.