@cryptotaxi247 / documentation-1
Code Commits Issues Pulls Sessions CI/CD
reggi/fix-transform-prettier
@reggi/path-to-regexp dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2 dependabot/npm_and_yarn/main/eslint-10.4.0 dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0 dependabot/npm_and_yarn/main/proc-log-7.0.0 dependabot/npm_and_yarn/npm_and_yarn-826852524d dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2 deprecate-totp-2fa dhei/classic-tokens gat-bypass-2fa-docs jpg619/fix-accessibility-content-flow jpg619/version-bump-tar-2 kartykp/gat-bypass-2fa-docs kartykp/upgrade-path-to-regex main maitxn/version-bump-tar patch-1 reggi/cache-based-on-version reggi/dev-engines reggi/fix-transform-prettier reggi/overrides update-search-sensitivity
mdx 180 lines 6.67 KB
Raw
1 ---
2 title: .npmrc
3 section: 5
4 description: The npm config files
5 github_repo: npm/cli
6 github_branch: latest
7 github_path: docs/lib/content/configuring-npm/npmrc.md
8 redirect_from:
9 - /cli-documentation/configuring-npm/npmrc
10 - /cli-documentation/files/npmrc
11 - /cli-documentation/v11/configuring-npm/npmrc
12 - /cli-documentation/v11/files/npmrc
13 - /cli/configuring-npm/npmrc
14 - /cli/files/npmrc
15 - /cli/v11/files/npmrc
16 - /configuring-npm/npmrc
17 - /files/npmrc
18 ---
19
20 ### Description
21
22 npm gets its config settings from the command line, environment variables, and `npmrc` files.
23
24 The `npm config` command can be used to update and edit the contents of the user and global npmrc files.
25
26 For a list of available configuration options, see [config](/cli/v11/using-npm/config).
27
28 ### Files
29
30 The four relevant files are:
31
32 - per-project config file (`/path/to/my/project/.npmrc`)
33 - per-user config file (`~/.npmrc`)
34 - global config file (`$PREFIX/etc/npmrc`)
35 - npm builtin config file (`/path/to/npm/npmrc`)
36
37 All npm config files are an ini-formatted list of `key = value` parameters. Environment variables can be replaced using `${VARIABLE_NAME}`. By default if the variable is not defined, it is left unreplaced. By adding `?` after variable name they can be forced to evaluate to an empty string instead. For example:
38
39 ```bash
40 cache = ${HOME}/.npm-packages
41 node-options = "${NODE_OPTIONS?} --use-system-ca"
42 ```
43
44 Each of these files is loaded, and config options are resolved in priority order. For example, a setting in the userconfig file would override the setting in the globalconfig file.
45
46 Array values are specified by adding "[]" after the key name. For example:
47
48 ```bash
49 key[] = "first value"
50 key[] = "second value"
51 ```
52
53 #### Comments
54
55 Lines in `.npmrc` files are interpreted as comments when they begin with a `;` or `#` character. `.npmrc` files are parsed by [npm/ini](https://github.com/npm/ini), which specifies this comment syntax.
56
57 For example:
58
59 ```bash
60 # last modified: 01 Jan 2016
61 ; Set a new registry for a scoped package
62 @myscope:registry=https://mycustomregistry.example.org
63 ```
64
65 #### Per-project config file
66
67 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.
68
69 Note that this only applies to the root of the project that you're running 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.
70
71 Additionally, this file is not read in global mode, such as when running `npm install -g`.
72
73 #### Per-user config file
74
75 `$HOME/.npmrc` (or the `userconfig` param, if set in the environment or on the command line)
76
77 #### Global config file
78
79 `$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.
80
81 #### Built-in config file
82
83 `path/to/npm/itself/npmrc`
84
85 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 maintainers to override default configs in a standard and consistent manner.
86
87 ### Auth related configuration
88
89 The settings `_auth`, `_authToken`, `username`, `_password`, `certfile`, and `keyfile` must all be scoped to a specific registry. This ensures that `npm` will never send credentials to the wrong host.
90
91 The full list is:
92
93 - `_auth` (base64 authentication string)
94 - `_authToken` (authentication token)
95 - `username`
96 - `_password`
97 - `email`
98 - `cafile` (path to certificate authority file)
99 - `certfile` (path to certificate file)
100 - `keyfile` (path to key file)
101
102 In order to scope these values, they must be prefixed by a URI fragment. 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:`.
103
104 ### Unsupported Custom Configuration Keys
105
106 Starting 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.
107
108 Only 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`.
109
110 If you need package-level configuration for use in scripts, use the `config` field in your `package.json` instead:
111
112 ```json
113 {
114 "name": "my-package",
115 "config": {
116 "mirror": "https://example.com/"
117 }
118 }
119 ```
120
121 Values defined in `package.json#config` are exposed to scripts as environment variables prefixed with `npm_package_config_`. For example:
122
123 ```
124 npm_package_config_mirror
125 ```
126
127 If you need to pass arguments to a script command, use `--` to separate npm arguments from script arguments:
128
129 ```
130 npm run build -- --customFlag
131 ```
132
133 Using environment variables is also recommended for cross-platform configuration instead of defining unsupported keys in `.npmrc`.
134
135 ```
136 ; bad config
137 _authToken=MYTOKEN
138
139 ; good config
140 @myorg:registry=https://somewhere-else.com/myorg
141 @another:registry=https://somewhere-else.com/another
142 //registry.npmjs.org/:_authToken=MYTOKEN
143
144 ; would apply to both @myorg and @another
145 //somewhere-else.com/:_authToken=MYTOKEN
146
147 ; would apply only to @myorg
148 //somewhere-else.com/myorg/:_authToken=MYTOKEN1
149
150 ; would apply only to @another
151 //somewhere-else.com/another/:_authToken=MYTOKEN2
152 ```
153
154 ### Custom / third-party config keys
155
156 npm only recognizes its own [configuration options](/cli/v11/using-npm/config). If your `.npmrc` contains keys that are not part of npm's config definitions (for example, `electron_mirror` or `sass_binary_site`), npm will emit a warning:
157
158 ```
159 warn Unknown user config "electron_mirror".
160 This will stop working in the next major version of npm.
161 ```
162
163 These keys were historically tolerated but are not officially supported. A future major version of npm will treat unknown top-level keys as errors.
164
165 Some tools (such as `@electron/get` or `node-sass`) read their own configuration from environment variables or from `.npmrc` by convention. You can set these values as environment variables instead:
166
167 ```bash
168 export ELECTRON_MIRROR="https://mirrorexample.npmjs.org/mirrors/electron/"
169 export ELECTRON_CUSTOM_DIR="{{ version }}"
170 ```
171
172 Environment variables are the most portable approach and work regardless of `.npmrc` format.
173
174 ### See also
175
176 - [npm folders](/cli/v11/configuring-npm/folders)
177 - [npm config](/cli/v11/commands/npm-config)
178 - [config](/cli/v11/using-npm/config)
179 - [package.json](/cli/v11/configuring-npm/package-json)
180 - [npm](/cli/v11/commands/npm)