codekingpro/portable-devtools

1---
2title: .npmrc
3section: 5
4description: The npm config files
5---
6
7### Description
8
9npm gets its config settings from the command line, environment variables, and `npmrc` files.
10
11The `npm config` command can be used to update and edit the contents of the user and global npmrc files.
12
13For a list of available configuration options, see [config](/using-npm/config).
14
15### Files
16
17The four relevant files are:
18
19* per-project config file (`/path/to/my/project/.npmrc`)
20* per-user config file (`~/.npmrc`)
21* global config file (`$PREFIX/etc/npmrc`)
22* npm builtin config file (`/path/to/npm/npmrc`)
23
24All npm config files are an ini-formatted list of `key = value` parameters.
25Environment variables can be replaced using `${VARIABLE_NAME}`.
26By default if the variable is not defined, it is left unreplaced.
27By adding `?` after variable name they can be forced to evaluate to an empty string instead.
28For example:
29
30```bash
31cache = ${HOME}/.npm-packages
32node-options = "${NODE_OPTIONS?} --use-system-ca"
33```
34
35Each of these files is loaded, and config options are resolved in priority order.
36For example, a setting in the userconfig file would override the setting in the globalconfig file.
37
38Array values are specified by adding "[]" after the key name.
39For example:
40
41```bash
42key[] = "first value"
43key[] = "second value"
44```
45
46#### Comments
47
48Lines in `.npmrc` files are interpreted as comments when they begin with a
49`;` or `#` character.
50`.npmrc` files are parsed by
51[npm/ini](https://github.com/npm/ini), which specifies this comment syntax.
52
53For example:
54
55```bash
56# last modified: 01 Jan 2016
57; Set a new registry for a scoped package
58@myscope:registry=https://mycustomregistry.example.org
59```
60
61#### Per-project config file
62
63When 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.
64
65Note that this only applies to the root of the project that you're running npm in.
66It has no effect when your module is published.
67For example, you can't publish a module that forces itself to install globally, or in a different location.
68
69Additionally, this file is not read in global mode, such as when running `npm install -g`.
70
71#### Per-user config file
72
73`$HOME/.npmrc` (or the `userconfig` param, if set in the environment or on the command line)
74
75#### Global config file
76
77`$PREFIX/etc/npmrc` (or the `globalconfig` param, if set above): This file is an ini-file formatted list of `key = value` parameters.
78Environment variables can be replaced as above.
79
80#### Built-in config file
81
82`path/to/npm/itself/npmrc`
83
84This is an unchangeable "builtin" configuration file that npm keeps consistent across updates.
85Set fields in here using the `./configure` script that comes with npm.
86This is primarily for distribution maintainers to override default configs in a standard and consistent manner.
87
88### Auth related configuration
89
90The settings `_auth`, `_authToken`, `username`, `_password`, `certfile`, and `keyfile` must all be scoped to a specific registry.
91This ensures that `npm` will never send credentials to the wrong host.
92
93The full list is:
94 - `_auth` (base64 authentication string)
95 - `_authToken` (authentication token)
96 - `username`
97 - `_password`
98 - `email`
99 - `cafile` (path to certificate authority file)
100 - `certfile` (path to certificate file)
101 - `keyfile` (path to key file)
102
103In order to scope these values, they must be prefixed by a URI fragment.
104If the credential is meant for any request to a registry on a single host, the scope may look like `//registry.npmjs.org/:`.
105If it must be scoped to a specific path on the host that path may also be provided, such as
106`//my-custom-registry.org/unique/path:`.
107
108### Unsupported Custom Configuration Keys
109
110Starting in npm v11.2.0, npm warns when unknown configuration keys are defined in `.npmrc`. In a future major version of npm, these unknown keys may no longer be accepted.
111
112Only configuration keys that npm officially supports are recognized. Custom keys intended for third-party tools (for example, `electron-builder`) should not be placed in `.npmrc`.
113
114If you need package-level configuration for use in scripts, use the `config` field in your `package.json` instead:
115
116```json
117{
118  "name": "my-package",
119  "config": {
120    "mirror": "https://example.com/"
121  }
122}
123
124```
125
126Values defined in `package.json#config` are exposed to scripts as environment variables prefixed with `npm_package_config_`. For example:
127
128```
129npm_package_config_mirror
130```
131
132If you need to pass arguments to a script command, use `--` to separate npm arguments from script arguments:
133
134```
135npm run build -- --customFlag
136```
137
138Using environment variables is also recommended for cross-platform configuration instead of defining unsupported keys in `.npmrc`.
139
140
141```
142; bad config
143_authToken=MYTOKEN
144
145; good config
146@myorg:registry=https://somewhere-else.com/myorg
147@another:registry=https://somewhere-else.com/another
148//registry.npmjs.org/:_authToken=MYTOKEN
149
150; would apply to both @myorg and @another
151//somewhere-else.com/:_authToken=MYTOKEN
152
153; would apply only to @myorg
154//somewhere-else.com/myorg/:_authToken=MYTOKEN1
155
156; would apply only to @another
157//somewhere-else.com/another/:_authToken=MYTOKEN2
158```
159
160### Custom / third-party config keys
161
162npm only recognizes its own [configuration options](/using-npm/config).
163If your `.npmrc` contains keys that are not part of npm's config definitions
164(for example, `electron_mirror` or `sass_binary_site`), npm will emit a
165warning:
166
167```
168warn Unknown user config "electron_mirror".
169This will stop working in the next major version of npm.
170```
171
172These keys were historically tolerated but are not officially supported.
173A future major version of npm will treat unknown top-level keys as errors.
174
175Some tools (such as `@electron/get` or `node-sass`) read their own
176configuration from environment variables or from `.npmrc` by convention.
177You can set these values as environment variables instead:
178
179```bash
180export ELECTRON_MIRROR="https://mirrorexample.npmjs.org/mirrors/electron/"
181export ELECTRON_CUSTOM_DIR="{{ version }}"
182```
183
184Environment variables are the most portable approach and work regardless
185of `.npmrc` format.
186
187### See also
188
189* [npm folders](/configuring-npm/folders)
190* [npm config](/commands/npm-config)
191* [config](/using-npm/config)
192* [package.json](/configuring-npm/package-json)
193* [npm](/commands/npm)
194