File Explorer

1.TH ".NPMRC" "5" "February 2026" "NPM@11.11.0" ""2.SH "NAME"3\fB.npmrc\fR - The npm config files4.SS "Description"5.P6npm gets its config settings from the command line, environment variables, and \fBnpmrc\fR files.7.P8The \fBnpm config\fR command can be used to update and edit the contents of the user and global npmrc files.9.P10For a list of available configuration options, see npm help config.11.SS "Files"12.P13The four relevant files are:14.RS 015.IP \(bu 416per-project config file (\fB/path/to/my/project/.npmrc\fR)17.IP \(bu 418per-user config file (\fB~/.npmrc\fR)19.IP \(bu 420global config file (\fB$PREFIX/etc/npmrc\fR)21.IP \(bu 422npm builtin config file (\fB/path/to/npm/npmrc\fR)23.RE 024 25.P26All npm config files are an ini-formatted list of \fBkey = value\fR parameters. Environment variables can be replaced using \fB${VARIABLE_NAME}\fR. By default if the variable is not defined, it is left unreplaced. By adding \fB?\fR after variable name they can be forced to evaluate to an empty string instead. For example:27.P28.RS 229.nf30cache = ${HOME}/.npm-packages31node-options = "${NODE_OPTIONS?} --use-system-ca"32.fi33.RE34.P35Each 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.36.P37Array values are specified by adding "\[lB]\[rB]" after the key name. For example:38.P39.RS 240.nf41key\[lB]\[rB] = "first value"42key\[lB]\[rB] = "second value"43.fi44.RE45.SS "Comments"46.P47Lines in \fB.npmrc\fR files are interpreted as comments when they begin with a \fB;\fR or \fB#\fR character. \fB.npmrc\fR files are parsed by \fBnpm/ini\fR \fI\(lahttps://github.com/npm/ini\(ra\fR, which specifies this comment syntax.48.P49For example:50.P51.RS 252.nf53# last modified: 01 Jan 201654; Set a new registry for a scoped package55@myscope:registry=https://mycustomregistry.example.org56.fi57.RE58.SS "Per-project config file"59.P60When working locally in a project, a \fB.npmrc\fR file in the root of the project (ie, a sibling of \fBnode_modules\fR and \fBpackage.json\fR) will set config values specific to this project.61.P62Note 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.63.P64Additionally, this file is not read in global mode, such as when running \fBnpm install -g\fR.65.SS "Per-user config file"66.P67\fB$HOME/.npmrc\fR (or the \fBuserconfig\fR param, if set in the environment or on the command line)68.SS "Global config file"69.P70\fB$PREFIX/etc/npmrc\fR (or the \fBglobalconfig\fR param, if set above): This file is an ini-file formatted list of \fBkey = value\fR parameters. Environment variables can be replaced as above.71.SS "Built-in config file"72.P73\fBpath/to/npm/itself/npmrc\fR74.P75This is an unchangeable "builtin" configuration file that npm keeps consistent across updates. Set fields in here using the \fB./configure\fR script that comes with npm. This is primarily for distribution maintainers to override default configs in a standard and consistent manner.76.SS "Auth related configuration"77.P78The settings \fB_auth\fR, \fB_authToken\fR, \fBusername\fR, \fB_password\fR, \fBcertfile\fR, and \fBkeyfile\fR must all be scoped to a specific registry. This ensures that \fBnpm\fR will never send credentials to the wrong host.79.P80The full list is:81.RS 082.IP \(bu 483\fB_auth\fR (base64 authentication string)84.IP \(bu 485\fB_authToken\fR (authentication token)86.IP \(bu 487\fBusername\fR88.IP \(bu 489\fB_password\fR90.IP \(bu 491\fBemail\fR92.IP \(bu 493\fBcafile\fR (path to certificate authority file)94.IP \(bu 495\fBcertfile\fR (path to certificate file)96.IP \(bu 497\fBkeyfile\fR (path to key file)98.RE 099 100.P101In 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 \fB//registry.npmjs.org/:\fR. If it must be scoped to a specific path on the host that path may also be provided, such as \fB//my-custom-registry.org/unique/path:\fR.102.SS "Unsupported Custom Configuration Keys"103.P104Starting in npm v11.2.0, npm warns when unknown configuration keys are defined in \fB.npmrc\fR. In a future major version of npm, these unknown keys may no longer be accepted.105.P106Only configuration keys that npm officially supports are recognized. Custom keys intended for third-party tools (for example, \fBelectron-builder\fR) should not be placed in \fB.npmrc\fR.107.P108If you need package-level configuration for use in scripts, use the \fBconfig\fR field in your \fBpackage.json\fR instead:109.P110.RS 2111.nf112{113  "name": "my-package",114  "config": {115    "mirror": "https://example.com/"116  }117}118 119.fi120.RE121.P122Values defined in \fBpackage.json#config\fR are exposed to scripts as environment variables prefixed with \fBnpm_package_config_\fR. For example:123.P124.RS 2125.nf126npm_package_config_mirror127.fi128.RE129.P130If you need to pass arguments to a script command, use \fB--\fR to separate npm arguments from script arguments:131.P132.RS 2133.nf134npm run build -- --customFlag135.fi136.RE137.P138Using environment variables is also recommended for cross-platform configuration instead of defining unsupported keys in \fB.npmrc\fR.139.P140.RS 2141.nf142; bad config143_authToken=MYTOKEN144 145; good config146@myorg:registry=https://somewhere-else.com/myorg147@another:registry=https://somewhere-else.com/another148//registry.npmjs.org/:_authToken=MYTOKEN149 150; would apply to both @myorg and @another151//somewhere-else.com/:_authToken=MYTOKEN152 153; would apply only to @myorg154//somewhere-else.com/myorg/:_authToken=MYTOKEN1155 156; would apply only to @another157//somewhere-else.com/another/:_authToken=MYTOKEN2158.fi159.RE160.SS "Custom / third-party config keys"161.P162npm only recognizes its own npm help "configuration options". If your \fB.npmrc\fR contains keys that are not part of npm's config definitions (for example, \fBelectron_mirror\fR or \fBsass_binary_site\fR), npm will emit a warning:163.P164.RS 2165.nf166warn Unknown user config "electron_mirror".167This will stop working in the next major version of npm.168.fi169.RE170.P171These keys were historically tolerated but are not officially supported. A future major version of npm will treat unknown top-level keys as errors.172.P173Some tools (such as \fB@electron/get\fR or \fBnode-sass\fR) read their own configuration from environment variables or from \fB.npmrc\fR by convention. You can set these values as environment variables instead:174.P175.RS 2176.nf177export ELECTRON_MIRROR="https://mirrorexample.npmjs.org/mirrors/electron/"178export ELECTRON_CUSTOM_DIR="{{ version }}"179.fi180.RE181.P182Environment variables are the most portable approach and work regardless of \fB.npmrc\fR format.183.SS "See also"184.RS 0185.IP \(bu 4186npm help folders187.IP \(bu 4188npm help config189.IP \(bu 4190npm help config191.IP \(bu 4192\fBpackage.json\fR \fI\(la/configuring-npm/package-json\(ra\fR193.IP \(bu 4194npm help npm195.RE 0196