1CONFIG(7) CONFIG(7)
2
6 config - More than you probably want to know about npm configuration
7 Description
9 npm gets its configuration values from the following sources, sorted by
10 priority:
11 Command Line Flags
13 Putting --foo bar on the command line sets the foo configuration param‐
14 eter to "bar". A -- argument tells the cli parser to stop reading
15 flags. Using --flag without specifying any value will set the value to
16 true.
17 Example: --flag1 --flag2 will set both configuration parameters to
19 true, while --flag1 --flag2 bar will set flag1 to true, and flag2 to
20 bar. Finally, --flag1 --flag2 -- bar will set both configuration pa‐
21 rameters to true, and the bar is taken as a command argument.
22 Environment Variables
24 Any environment variables that start with npm_config_ will be inter‐
25 preted as a configuration parameter. For example, putting npm_con‐
26 fig_foo=bar in your environment will set the foo configuration parame‐
27 ter to bar. Any environment configurations that are not given a value
28 will be given the value of true. Config values are case-insensitive,
29 so NPM_CONFIG_FOO=bar will work the same. However, please note that in‐
30 side npm help scripts npm will set its own environment variables and
31 Node will prefer those lowercase versions over any uppercase ones that
32 you might set. For details see this issue
33 https://github.com/npm/npm/issues/14528.
34 Notice that you need to use underscores instead of dashes, so --al‐
36 low-same-version would become npm_config_allow_same_version=true.
37 npmrc Files
39 The four relevant files are:
40 • per-project configuration file (/path/to/my/project/.npmrc)
42 • per-user configuration file (defaults to $HOME/.npmrc; configurable
44 via CLI option --userconfig or environment variable $NPM_CONFIG_USER‐
45 CONFIG)
46 • global configuration file (defaults to $PREFIX/etc/npmrc; config‐
48 urable via CLI option --globalconfig or environment variable
49 $NPM_CONFIG_GLOBALCONFIG)
50 • npm's built-in configuration file (/path/to/npm/npmrc)
52 See npm help npmrc for more details.
55 Default Configs
57 Run npm config ls -l to see a set of configuration parameters that are
58 internal to npm, and are defaults if nothing else is specified.
59 Shorthands and Other CLI Niceties
61 The following shorthands are parsed on the command-line:
62 • -a: --all
64 • --enjoy-by: --before
66 • -c: --call
68 • --desc: --description
70 • -f: --force
72 • -g: --global
74 • --iwr: --include-workspace-root
76 • -L: --location
78 • -d: --loglevel info
80 • -s: --loglevel silent
82 • --silent: --loglevel silent
84 • --ddd: --loglevel silly
86 • --dd: --loglevel verbose
88 • --verbose: --loglevel verbose
90 • -q: --loglevel warn
92 • --quiet: --loglevel warn
94 • -l: --long
96 • -m: --message
98 • --local: --no-global
100 • -n: --no-yes
102 • --no: --no-yes
104 • -p: --parseable
106 • --porcelain: --parseable
108 • -C: --prefix
110 • --readonly: --read-only
112 • --reg: --registry
114 • -S: --save
116 • -B: --save-bundle
118 • -D: --save-dev
120 • -E: --save-exact
122 • -O: --save-optional
124 • -P: --save-prod
126 • -?: --usage
128 • -h: --usage
130 • -H: --usage
132 • --help: --usage
134 • -v: --version
136 • -w: --workspace
138 • --ws: --workspaces
140 • -y: --yes
142 If the specified configuration param resolves unambiguously to a known
145 configuration parameter, then it is expanded to that configuration pa‐
146 rameter. For example:
147 npm ls --par
149 # same as:
150 npm ls --parseable
151 If multiple single-character shorthands are strung together, and the
153 resulting combination is unambiguously not some other configuration
154 param, then it is expanded to its various component pieces. For exam‐
155 ple:
156 npm ls -gpld
158 # same as:
159 npm ls --global --parseable --long --loglevel info
160 Config Settings
162 _auth
163 • Default: null
164 • Type: null or String
166 A basic-auth string to use when authenticating against the npm reg‐
169 istry. This will ONLY be used to authenticate against the npm reg‐
170 istry. For other registries you will need to scope it like
171 "//other-registry.tld/:_auth"
172 Warning: This should generally not be set via a command-line option. It
174 is safer to use a registry-provided authentication bearer token stored
175 in the ~/.npmrc file by running npm login.
176 access
178 • Default: 'restricted' for scoped packages, 'public' for unscoped
179 packages
180 • Type: null, "restricted", or "public"
182 When publishing scoped packages, the access level defaults to re‐
185 stricted. If you want your scoped package to be publicly viewable (and
186 installable) set --access=public. The only valid values for access are
187 public and restricted. Unscoped packages always have an access level of
188 public.
189 Note: Using the --access flag on the npm publish command will only set
191 the package access level on the initial publish of the package. Any
192 subsequent npm publish commands using the --access flag will not have
193 an effect to the access level. To make changes to the access level af‐
194 ter the initial publish use npm access.
195 all
197 • Default: false
198 • Type: Boolean
200 When running npm outdated and npm ls, setting --all will show all out‐
203 dated or installed packages, rather than only those directly depended
204 upon by the current project.
205 allow-same-version
207 • Default: false
208 • Type: Boolean
210 Prevents throwing an error when npm version is used to set the new ver‐
213 sion to the same value as the current version.
214 audit
216 • Default: true
217 • Type: Boolean
219 When "true" submit audit reports alongside the current npm command to
222 the default registry and all registries configured for scopes. See the
223 documentation for npm help audit for details on what is submitted.
224 audit-level
226 • Default: null
227 • Type: null, "info", "low", "moderate", "high", "critical", or "none"
229 The minimum level of vulnerability for npm audit to exit with a
232 non-zero exit code.
233 auth-type
235 • Default: "legacy"
236 • Type: "legacy", "web", "sso", "saml", "oauth", or "webauthn"
238 NOTE: auth-type values "sso", "saml", "oauth", and "webauthn" will be
241 removed in a future version.
242 What authentication strategy to use with login.
244 before
246 • Default: null
247 • Type: null or Date
249 If passed to npm install, will rebuild the npm tree such that only ver‐
252 sions that were available on or before the --before time get installed.
253 If there's no versions available for the current set of direct depen‐
254 dencies, the command will error.
255 If the requested version is a dist-tag and the given tag does not pass
257 the --before filter, the most recent version less than or equal to that
258 tag will be used. For example, foo@latest might install foo@1.2 even
259 though latest is 2.0.
260 bin-links
262 • Default: true
263 • Type: Boolean
265 Tells npm to create symlinks (or .cmd shims on Windows) for package ex‐
268 ecutables.
269 Set to false to have it not do this. This can be used to work around
271 the fact that some file systems don't support symlinks, even on osten‐
272 sibly Unix systems.
273 browser
275 • Default: OS X: "open", Windows: "start", Others: "xdg-open"
276 • Type: null, Boolean, or String
278 The browser that is called by npm commands to open websites.
281 Set to false to suppress browser behavior and instead print urls to
283 terminal.
284 Set to true to use default system URL opener.
286 ca
288 • Default: null
289 • Type: null or String (can be set multiple times)
291 The Certificate Authority signing certificate that is trusted for SSL
294 connections to the registry. Values should be in PEM format (Windows
295 calls it "Base-64 encoded X.509 (.CER)") with newlines replaced by the
296 string "\n". For example:
297 ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"
299 Set to null to only allow "known" registrars, or to a specific CA cert
301 to trust only that specific signing authority.
302 Multiple CAs can be trusted by specifying an array of certificates:
304 ca[]="..."
306 ca[]="..."
307 See also the strict-ssl config.
309 cache
311 • Default: Windows: %LocalAppData%\npm-cache, Posix: ~/.npm
312 • Type: Path
314 The location of npm's cache directory. See npm help npm cache
317 cafile
319 • Default: null
320 • Type: Path
322 A path to a file containing one or multiple Certificate Authority sign‐
325 ing certificates. Similar to the ca setting, but allows for multiple
326 CA's, as well as for the CA information to be stored in a file on disk.
327 call
329 • Default: ""
330 • Type: String
332 Optional companion option for npm exec, npx that allows for specifying
335 a custom command to be run along with the installed packages.
336 npm exec --package yo --package generator-node --call "yo node"
338 cert
340 • Default: null
341 • Type: null or String
343 A client certificate to pass when accessing the registry. Values should
346 be in PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with
347 newlines replaced by the string "\n". For example:
348 cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"
350 It is not the path to a certificate file, though you can set a reg‐
352 istry-scoped "certfile" path like "//other-registry.tld/:cert‐
353 file=/path/to/cert.pem".
354 ci-name
356 • Default: The name of the current CI system, or null when not on a
357 known CI platform.
358 • Type: null or String
360 The name of a continuous integration system. If not set explicitly, npm
363 will detect the current CI environment using the @npmcli/ci-detect
364 http://npm.im/@npmcli/ci-detect module.
365 cidr
367 • Default: null
368 • Type: null or String (can be set multiple times)
370 This is a list of CIDR address to be used when configuring limited ac‐
373 cess tokens with the npm token create command.
374 color
376 • Default: true unless the NO_COLOR environ is set to something other
377 than '0'
378 • Type: "always" or Boolean
380 If false, never shows colors. If "always" then always shows colors. If
383 true, then only prints color codes for tty file descriptors.
384 commit-hooks
386 • Default: true
387 • Type: Boolean
389 Run git commit hooks when using the npm version command.
392 depth
394 • Default: Infinity if --all is set, otherwise 1
395 • Type: null or Number
397 The depth to go when recursing packages for npm ls.
400 If not set, npm ls will show only the immediate dependencies of the
402 root project. If --all is set, then npm will show all dependencies by
403 default.
404 description
406 • Default: true
407 • Type: Boolean
409 Show the description in npm search
412 diff
414 • Default:
415 • Type: String (can be set multiple times)
417 Define arguments to compare in npm diff.
420 diff-dst-prefix
422 • Default: "b/"
423 • Type: String
425 Destination prefix to be used in npm diff output.
428 diff-ignore-all-space
430 • Default: false
431 • Type: Boolean
433 Ignore whitespace when comparing lines in npm diff.
436 diff-name-only
438 • Default: false
439 • Type: Boolean
441 Prints only filenames when using npm diff.
444 diff-no-prefix
446 • Default: false
447 • Type: Boolean
449 Do not show any source or destination prefix in npm diff output.
452 Note: this causes npm diff to ignore the --diff-src-prefix and
454 --diff-dst-prefix configs.
455 diff-src-prefix
457 • Default: "a/"
458 • Type: String
460 Source prefix to be used in npm diff output.
463 diff-text
465 • Default: false
466 • Type: Boolean
468 Treat all files as text in npm diff.
471 diff-unified
473 • Default: 3
474 • Type: Number
476 The number of lines of context to print in npm diff.
479 dry-run
481 • Default: false
482 • Type: Boolean
484 Indicates that you don't want npm to make any changes and that it
487 should only report what it would have done. This can be passed into any
488 of the commands that modify your local installation, eg, install, up‐
489 date, dedupe, uninstall, as well as pack and publish.
490 Note: This is NOT honored by other network related commands, eg
492 dist-tags, owner, etc.
493 editor
495 • Default: The EDITOR or VISUAL environment variables, or 'notepad.exe'
496 on Windows, or 'vim' on Unix systems
497 • Type: String
499 The command to run for npm edit and npm config edit.
502 engine-strict
504 • Default: false
505 • Type: Boolean
507 If set to true, then npm will stubbornly refuse to install (or even
510 consider installing) any package that claims to not be compatible with
511 the current Node.js version.
512 This can be overridden by setting the --force flag.
514 fetch-retries
516 • Default: 2
517 • Type: Number
519 The "retries" config for the retry module to use when fetching packages
522 from the registry.
523 npm will retry idempotent read requests to the registry in the case of
525 network failures or 5xx HTTP errors.
526 fetch-retry-factor
528 • Default: 10
529 • Type: Number
531 The "factor" config for the retry module to use when fetching packages.
534 fetch-retry-maxtimeout
536 • Default: 60000 (1 minute)
537 • Type: Number
539 The "maxTimeout" config for the retry module to use when fetching pack‐
542 ages.
543 fetch-retry-mintimeout
545 • Default: 10000 (10 seconds)
546 • Type: Number
548 The "minTimeout" config for the retry module to use when fetching pack‐
551 ages.
552 fetch-timeout
554 • Default: 300000 (5 minutes)
555 • Type: Number
557 The maximum amount of time to wait for HTTP requests to complete.
560 force
562 • Default: false
563 • Type: Boolean
565 Removes various protections against unfortunate side effects, common
568 mistakes, unnecessary performance degradation, and malicious input.
569 • Allow clobbering non-npm files in global installs.
571 • Allow the npm version command to work on an unclean git repository.
573 • Allow deleting the cache folder with npm cache clean.
575 • Allow installing packages that have an engines declaration requiring
577 a different version of npm.
578 • Allow installing packages that have an engines declaration requiring
580 a different version of node, even if --engine-strict is enabled.
581 • Allow npm audit fix to install modules outside your stated dependency
583 range (including SemVer-major changes).
584 • Allow unpublishing all versions of a published package.
586 • Allow conflicting peerDependencies to be installed in the root
588 project.
589 • Implicitly set --yes during npm init.
591 • Allow clobbering existing values in npm pkg
593 • Allow unpublishing of entire packages (not just a single version).
595 If you don't have a clear idea of what you want to do, it is strongly
598 recommended that you do not use this option!
599 foreground-scripts
601 • Default: false
602 • Type: Boolean
604 Run all build scripts (ie, preinstall, install, and postinstall)
607 scripts for installed packages in the foreground process, sharing stan‐
608 dard input, output, and error with the main npm process.
609 Note that this will generally make installs run slower, and be much
611 noisier, but can be useful for debugging.
612 format-package-lock
614 • Default: true
615 • Type: Boolean
617 Format package-lock.json or npm-shrinkwrap.json as a human readable
620 file.
621 fund
623 • Default: true
624 • Type: Boolean
626 When "true" displays the message at the end of each npm install ac‐
629 knowledging the number of dependencies looking for funding. See npm
630 help npm fund for details.
631 git
633 • Default: "git"
634 • Type: String
636 The command to use for git commands. If git is installed on the com‐
639 puter, but is not in the PATH, then set this to the full path to the
640 git binary.
641 git-tag-version
643 • Default: true
644 • Type: Boolean
646 Tag the commit when using the npm version command. Setting this to
649 false results in no commit being made at all.
650 global
652 • Default: false
653 • Type: Boolean
655 Operates in "global" mode, so that packages are installed into the pre‐
658 fix folder instead of the current working directory. See npm help fold‐
659 ers for more on the differences in behavior.
660 • packages are installed into the {prefix}/lib/node_modules folder, in‐
662 stead of the current working directory.
663 • bin files are linked to {prefix}/bin
665 • man pages are linked to {prefix}/share/man
667 global-style
670 • Default: false
671 • Type: Boolean
673 Causes npm to install the package into your local node_modules folder
676 with the same layout it uses with the global node_modules folder. Only
677 your direct dependencies will show in node_modules and everything they
678 depend on will be flattened in their node_modules folders. This obvi‐
679 ously will eliminate some deduping. If used with legacy-bundling,
680 legacy-bundling will be preferred.
681 globalconfig
683 • Default: The global --prefix setting plus 'etc/npmrc'. For example,
684 '/usr/local/etc/npmrc'
685 • Type: Path
687 The config file to read for global config options.
690 heading
692 • Default: "npm"
693 • Type: String
695 The string that starts all the debugging log output.
698 https-proxy
700 • Default: null
701 • Type: null or URL
703 A proxy to use for outgoing https requests. If the HTTPS_PROXY or
706 https_proxy or HTTP_PROXY or http_proxy environment variables are set,
707 proxy settings will be honored by the underlying make-fetch-happen li‐
708 brary.
709 if-present
711 • Default: false
712 • Type: Boolean
714 If true, npm will not exit with an error code when run-script is in‐
717 voked for a script that isn't defined in the scripts section of pack‐
718 age.json. This option can be used when it's desirable to optionally
719 run a script when it's present and fail if the script fails. This is
720 useful, for example, when running scripts that may only apply for some
721 builds in an otherwise generic CI setup.
722 This value is not exported to the environment for child processes.
724 ignore-scripts
726 • Default: false
727 • Type: Boolean
729 If true, npm does not run scripts specified in package.json files.
732 Note that commands explicitly intended to run a particular script, such
734 as npm start, npm stop, npm restart, npm test, and npm run-script will
735 still run their intended script if ignore-scripts is set, but they will
736 not run any pre- or post-scripts.
737 include
739 • Default:
740 • Type: "prod", "dev", "optional", or "peer" (can be set multiple
742 times)
743 Option that allows for defining which types of dependencies to install.
746 This is the inverse of --omit=<type>.
748 Dependency types specified in --include will not be omitted, regardless
750 of the order in which omit/include are specified on the command-line.
751 include-staged
753 • Default: false
754 • Type: Boolean
756 Allow installing "staged" published packages, as defined by npm RFC PR
759 #92 https://github.com/npm/rfcs/pull/92.
760 This is experimental, and not implemented by the npm public registry.
762 include-workspace-root
764 • Default: false
765 • Type: Boolean
767 Include the workspace root when workspaces are enabled for a command.
770 When false, specifying individual workspaces via the workspace config,
772 or all workspaces via the workspaces flag, will cause npm to operate
773 only on the specified workspaces, and not on the root project.
774 This value is not exported to the environment for child processes.
776 init-author-email
778 • Default: ""
779 • Type: String
781 The value npm init should use by default for the package author's
784 email.
785 init-author-name
787 • Default: ""
788 • Type: String
790 The value npm init should use by default for the package author's name.
793 init-author-url
795 • Default: ""
796 • Type: "" or URL
798 The value npm init should use by default for the package author's home‐
801 page.
802 init-license
804 • Default: "ISC"
805 • Type: String
807 The value npm init should use by default for the package license.
810 init-module
812 • Default: "~/.npm-init.js"
813 • Type: Path
815 A module that will be loaded by the npm init command. See the documen‐
818 tation for the init-package-json https://github.com/npm/init-pack‐
819 age-json module for more information, or npm help init.
820 init-version
822 • Default: "1.0.0"
823 • Type: SemVer string
825 The value that npm init should use by default for the package version
828 number, if not already set in package.json.
829 install-links
831 • Default: false
832 • Type: Boolean
834 When set file: protocol dependencies that exist outside of the project
837 root will be packed and installed as regular dependencies instead of
838 creating a symlink. This option has no effect on workspaces.
839 json
841 • Default: false
842 • Type: Boolean
844 Whether or not to output JSON data, rather than the normal output.
847 • In npm pkg set it enables parsing set values with JSON.parse() before
849 saving them to your package.json.
850 Not supported by all npm commands.
853 key
855 • Default: null
856 • Type: null or String
858 A client key to pass when accessing the registry. Values should be in
861 PEM format with newlines replaced by the string "\n". For example:
862 key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"
864 It is not the path to a key file, though you can set a registry-scoped
866 "keyfile" path like "//other-registry.tld/:keyfile=/path/to/key.pem".
867 legacy-bundling
869 • Default: false
870 • Type: Boolean
872 Causes npm to install the package such that versions of npm prior to
875 1.4, such as the one included with node 0.8, can install the package.
876 This eliminates all automatic deduping. If used with global-style this
877 option will be preferred.
878 legacy-peer-deps
880 • Default: false
881 • Type: Boolean
883 Causes npm to completely ignore peerDependencies when building a pack‐
886 age tree, as in npm versions 3 through 6.
887 If a package cannot be installed because of overly strict peerDependen‐
889 cies that collide, it provides a way to move forward resolving the sit‐
890 uation.
891 This differs from --omit=peer, in that --omit=peer will avoid unpacking
893 peerDependencies on disk, but will still design a tree such that
894 peerDependencies could be unpacked in a correct place.
895 Use of legacy-peer-deps is not recommended, as it will not enforce the
897 peerDependencies contract that meta-dependencies may rely on.
898 link
900 • Default: false
901 • Type: Boolean
903 Used with npm ls, limiting output to only those packages that are
906 linked.
907 local-address
909 • Default: null
910 • Type: IP Address
912 The IP address of the local interface to use when making connections to
915 the npm registry. Must be IPv4 in versions of Node prior to 0.12.
916 location
918 • Default: "user" unless --global is passed, which will also set this
919 value to "global"
920 • Type: "global", "user", or "project"
922 When passed to npm config this refers to which config file to use.
925 When set to "global" mode, packages are installed into the prefix
927 folder instead of the current working directory. See npm help folders
928 for more on the differences in behavior.
929 • packages are installed into the {prefix}/lib/node_modules folder, in‐
931 stead of the current working directory.
932 • bin files are linked to {prefix}/bin
934 • man pages are linked to {prefix}/share/man
936 lockfile-version
939 • Default: Version 2 if no lockfile or current lockfile version less
940 than or equal to 2, otherwise maintain current lockfile version
941 • Type: null, 1, 2, 3, "1", "2", or "3"
943 Set the lockfile format version to be used in package-lock.json and
946 npm-shrinkwrap-json files. Possible options are:
947 1: The lockfile version used by npm versions 5 and 6. Lacks some data
949 that is used during the install, resulting in slower and possibly less
950 deterministic installs. Prevents lockfile churn when interoperating
951 with older npm versions.
952 2: The default lockfile version used by npm version 7. Includes both
954 the version 1 lockfile data and version 3 lockfile data, for maximum
955 determinism and interoperability, at the expense of more bytes on disk.
956 3: Only the new lockfile information introduced in npm version 7.
958 Smaller on disk than lockfile version 2, but not interoperable with
959 older npm versions. Ideal if all users are on npm version 7 and
960 higher.
961 loglevel
963 • Default: "notice"
964 • Type: "silent", "error", "warn", "notice", "http", "timing", "info",
966 "verbose", or "silly"
967 What level of logs to report. All logs are written to a debug log, with
970 the path to that file printed if the execution of a command fails.
971 Any logs of a higher level than the setting are shown. The default is
973 "notice".
974 See also the foreground-scripts config.
976 logs-dir
978 • Default: A directory named _logs inside the cache
979 • Type: null or Path
981 The location of npm's log directory. See npm help logging for more in‐
984 formation.
985 logs-max
987 • Default: 10
988 • Type: Number
990 The maximum number of log files to store.
993 If set to 0, no log files will be written for the current run.
995 long
997 • Default: false
998 • Type: Boolean
1000 Show extended information in ls, search, and help-search.
1003 maxsockets
1005 • Default: 15
1006 • Type: Number
1008 The maximum number of connections to use per origin (protocol/host/port
1011 combination).
1012 message
1014 • Default: "%s"
1015 • Type: String
1017 Commit message which is used by npm version when creating version com‐
1020 mit.
1021 Any "%s" in the message will be replaced with the version number.
1023 node-options
1025 • Default: null
1026 • Type: null or String
1028 Options to pass through to Node.js via the NODE_OPTIONS environment
1031 variable. This does not impact how npm itself is executed but it does
1032 impact how lifecycle scripts are called.
1033 node-version
1035 • Default: Node.js process.version value
1036 • Type: SemVer string
1038 The node version to use when checking a package's engines setting.
1041 noproxy
1043 • Default: The value of the NO_PROXY environment variable
1044 • Type: String (can be set multiple times)
1046 Domain extensions that should bypass any proxies.
1049 Also accepts a comma-delimited string.
1051 npm-version
1053 • Default: Output of npm --version
1054 • Type: SemVer string
1056 The npm version to use when checking a package's engines setting.
1059 offline
1061 • Default: false
1062 • Type: Boolean
1064 Force offline mode: no network requests will be done during install. To
1067 allow the CLI to fill in missing cache data, see --prefer-offline.
1068 omit
1070 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
1071 duction', otherwise empty.
1072 • Type: "dev", "optional", or "peer" (can be set multiple times)
1074 Dependency types to omit from the installation tree on disk.
1077 Note that these dependencies are still resolved and added to the pack‐
1079 age-lock.json or npm-shrinkwrap.json file. They are just not physically
1080 installed on disk.
1081 If a package type appears in both the --include and --omit lists, then
1083 it will be included.
1084 If the resulting omit list includes 'dev', then the NODE_ENV environ‐
1086 ment variable will be set to 'production' for all lifecycle scripts.
1087 omit-lockfile-registry-resolved
1089 • Default: false
1090 • Type: Boolean
1092 This option causes npm to create lock files without a resolved key for
1095 registry dependencies. Subsequent installs will need to resolve tarball
1096 endpoints with the configured registry, likely resulting in a longer
1097 install time.
1098 otp
1100 • Default: null
1101 • Type: null or String
1103 This is a one-time password from a two-factor authenticator. It's
1106 needed when publishing or changing package permissions with npm access.
1107 If not set, and a registry response fails with a challenge for a
1109 one-time password, npm will prompt on the command line for one.
1110 pack-destination
1112 • Default: "."
1113 • Type: String
1115 Directory in which npm pack will save tarballs.
1118 package
1120 • Default:
1121 • Type: String (can be set multiple times)
1123 The package or packages to install for npm help exec
1126 package-lock
1128 • Default: true
1129 • Type: Boolean
1131 If set to false, then ignore package-lock.json files when installing.
1134 This will also prevent writing package-lock.json if save is true.
1135 This configuration does not affect npm ci.
1137 package-lock-only
1139 • Default: false
1140 • Type: Boolean
1142 If set to true, the current operation will only use the pack‐
1145 age-lock.json, ignoring node_modules.
1146 For update this means only the package-lock.json will be updated, in‐
1148 stead of checking node_modules and downloading dependencies.
1149 For list this means the output will be based on the tree described by
1151 the package-lock.json, rather than the contents of node_modules.
1152 parseable
1154 • Default: false
1155 • Type: Boolean
1157 Output parseable results from commands that write to standard output.
1160 For npm search, this will be tab-separated table format.
1161 prefer-offline
1163 • Default: false
1164 • Type: Boolean
1166 If true, staleness checks for cached data will be bypassed, but missing
1169 data will be requested from the server. To force full offline mode, use
1170 --offline.
1171 prefer-online
1173 • Default: false
1174 • Type: Boolean
1176 If true, staleness checks for cached data will be forced, making the
1179 CLI look for updates immediately even for fresh package data.
1180 prefix
1182 • Default: In global mode, the folder where the node executable is in‐
1183 stalled. In local mode, the nearest parent folder containing either
1184 a package.json file or a node_modules folder.
1185 • Type: Path
1187 The location to install global items. If set on the command line, then
1190 it forces non-global commands to run in the specified folder.
1191 preid
1193 • Default: ""
1194 • Type: String
1196 The "prerelease identifier" to use as a prefix for the "prerelease"
1199 part of a semver. Like the rc in 1.2.0-rc.8.
1200 progress
1202 • Default: true unless running in a known CI system
1203 • Type: Boolean
1205 When set to true, npm will display a progress bar during time intensive
1208 operations, if process.stderr is a TTY.
1209 Set to false to suppress the progress bar.
1211 proxy
1213 • Default: null
1214 • Type: null, false, or URL
1216 A proxy to use for outgoing http requests. If the HTTP_PROXY or
1219 http_proxy environment variables are set, proxy settings will be hon‐
1220 ored by the underlying request library.
1221 read-only
1223 • Default: false
1224 • Type: Boolean
1226 This is used to mark a token as unable to publish when configuring lim‐
1229 ited access tokens with the npm token create command.
1230 rebuild-bundle
1232 • Default: true
1233 • Type: Boolean
1235 Rebuild bundled dependencies after installation.
1238 registry
1240 • Default: "https://registry.npmjs.org/"
1241 • Type: URL
1243 The base URL of the npm registry.
1246 replace-registry-host
1248 • Default: "npmjs"
1249 • Type: "npmjs", "never", "always", or String
1251 Defines behavior for replacing the registry host in a lockfile with the
1254 configured registry.
1255 The default behavior is to replace package dist URLs from the default
1257 registry (https://registry.npmjs.org) to the configured registry. If
1258 set to "never", then use the registry value. If set to "always", then
1259 replace the registry host with the configured host every time.
1260 You may also specify a bare hostname (e.g., "registry.npmjs.org").
1262 save
1264 • Default: true unless when using npm update where it defaults to false
1265 • Type: Boolean
1267 Save installed packages to a package.json file as dependencies.
1270 When used with the npm rm command, removes the dependency from pack‐
1272 age.json.
1273 Will also prevent writing to package-lock.json if set to false.
1275 save-bundle
1277 • Default: false
1278 • Type: Boolean
1280 If a package would be saved at install time by the use of --save,
1283 --save-dev, or --save-optional, then also put it in the bundleDependen‐
1284 cies list.
1285 Ignored if --save-peer is set, since peerDependencies cannot be bun‐
1287 dled.
1288 save-dev
1290 • Default: false
1291 • Type: Boolean
1293 Save installed packages to a package.json file as devDependencies.
1296 save-exact
1298 • Default: false
1299 • Type: Boolean
1301 Dependencies saved to package.json will be configured with an exact
1304 version rather than using npm's default semver range operator.
1305 save-optional
1307 • Default: false
1308 • Type: Boolean
1310 Save installed packages to a package.json file as optionalDependencies.
1313 save-peer
1315 • Default: false
1316 • Type: Boolean
1318 Save installed packages to a package.json file as peerDependencies
1321 save-prefix
1323 • Default: "^"
1324 • Type: String
1326 Configure how versions of packages installed to a package.json file via
1329 --save or --save-dev get prefixed.
1330 For example if a package has version 1.2.3, by default its version is
1332 set to ^1.2.3 which allows minor upgrades for that package, but after
1333 npm config set save-prefix='~' it would be set to ~1.2.3 which only al‐
1334 lows patch upgrades.
1335 save-prod
1337 • Default: false
1338 • Type: Boolean
1340 Save installed packages into dependencies specifically. This is useful
1343 if a package already exists in devDependencies or optionalDependencies,
1344 but you want to move it to be a non-optional production dependency.
1345 This is the default behavior if --save is true, and neither --save-dev
1347 or --save-optional are true.
1348 scope
1350 • Default: the scope of the current project, if any, or ""
1351 • Type: String
1353 Associate an operation with a scope for a scoped registry.
1356 Useful when logging in to or out of a private registry:
1358 # log in, linking the scope to the custom registry
1360 npm login --scope=@mycorp --registry=https://registry.mycorp.com
1361 # log out, removing the link and the auth token
1363 npm logout --scope=@mycorp
1364 This will cause @mycorp to be mapped to the registry for future instal‐
1366 lation of packages specified according to the pattern @mycorp/package.
1367 This will also cause npm init to create a scoped package.
1369 # accept all defaults, and create a package named "@foo/whatever",
1371 # instead of just named "whatever"
1372 npm init --scope=@foo --yes
1373 script-shell
1375 • Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows
1376 • Type: null or String
1378 The shell to use for scripts run with the npm exec, npm run and npm
1381 init <package-spec> commands.
1382 searchexclude
1384 • Default: ""
1385 • Type: String
1387 Space-separated options that limit the results from search.
1390 searchlimit
1392 • Default: 20
1393 • Type: Number
1395 Number of items to limit search results to. Will not apply at all to
1398 legacy searches.
1399 searchopts
1401 • Default: ""
1402 • Type: String
1404 Space-separated options that are always passed to search.
1407 searchstaleness
1409 • Default: 900
1410 • Type: Number
1412 The age of the cache, in seconds, before another registry request is
1415 made if using legacy search endpoint.
1416 shell
1418 • Default: SHELL environment variable, or "bash" on Posix, or "cmd.exe"
1419 on Windows
1420 • Type: String
1422 The shell to run for the npm explore command.
1425 sign-git-commit
1427 • Default: false
1428 • Type: Boolean
1430 If set to true, then the npm version command will commit the new pack‐
1433 age version using -S to add a signature.
1434 Note that git requires you to have set up GPG keys in your git configs
1436 for this to work properly.
1437 sign-git-tag
1439 • Default: false
1440 • Type: Boolean
1442 If set to true, then the npm version command will tag the version using
1445 -s to add a signature.
1446 Note that git requires you to have set up GPG keys in your git configs
1448 for this to work properly.
1449 strict-peer-deps
1451 • Default: false
1452 • Type: Boolean
1454 If set to true, and --legacy-peer-deps is not set, then any conflicting
1457 peerDependencies will be treated as an install failure, even if npm
1458 could reasonably guess the appropriate resolution based on non-peer de‐
1459 pendency relationships.
1460 By default, conflicting peerDependencies deep in the dependency graph
1462 will be resolved using the nearest non-peer dependency specification,
1463 even if doing so will result in some packages receiving a peer depen‐
1464 dency outside the range set in their package's peerDependencies object.
1465 When such and override is performed, a warning is printed, explaining
1467 the conflict and the packages involved. If --strict-peer-deps is set,
1468 then this warning is treated as a failure.
1469 strict-ssl
1471 • Default: true
1472 • Type: Boolean
1474 Whether or not to do SSL key validation when making requests to the
1477 registry via https.
1478 See also the ca config.
1480 tag
1482 • Default: "latest"
1483 • Type: String
1485 If you ask npm to install a package and don't tell it a specific ver‐
1488 sion, then it will install the specified tag.
1489 Also the tag that is added to the package@version specified by the npm
1491 tag command, if no explicit tag is given.
1492 When used by the npm diff command, this is the tag used to fetch the
1494 tarball that will be compared with the local files by default.
1495 tag-version-prefix
1497 • Default: "v"
1498 • Type: String
1500 If set, alters the prefix used when tagging a new version when perform‐
1503 ing a version increment using npm-version. To remove the prefix alto‐
1504 gether, set it to the empty string: "".
1505 Because other tools may rely on the convention that npm version tags
1507 look like v1.0.0, only use this property if it is absolutely necessary.
1508 In particular, use care when overriding this setting for public pack‐
1509 ages.
1510 timing
1512 • Default: false
1513 • Type: Boolean
1515 If true, writes a debug log to logs-dir and timing information to _tim‐
1518 ing.json in the cache, even if the command completes successfully.
1519 _timing.json is a newline delimited list of JSON objects.
1520 You can quickly view it with this json https://npm.im/json command
1522 line: npm exec -- json -g < ~/.npm/_timing.json.
1523 umask
1525 • Default: 0
1526 • Type: Octal numeric string in range 0000..0777 (0..511)
1528 The "umask" value to use when setting the file creation mode on files
1531 and folders.
1532 Folders and executables are given a mode which is 0o777 masked against
1534 this value. Other files are given a mode which is 0o666 masked against
1535 this value.
1536 Note that the underlying system will also apply its own umask value to
1538 files and folders that are created, and npm does not circumvent this,
1539 but rather adds the --umask config to it.
1540 Thus, the effective default umask value on most POSIX systems is 0o22,
1542 meaning that folders and executables are created with a mode of 0o755
1543 and other files are created with a mode of 0o644.
1544 unicode
1546 • Default: false on windows, true on mac/unix systems with a unicode
1547 locale, as defined by the LC_ALL, LC_CTYPE, or LANG environment vari‐
1548 ables.
1549 • Type: Boolean
1551 When set to true, npm uses unicode characters in the tree output. When
1554 false, it uses ascii characters instead of unicode glyphs.
1555 update-notifier
1557 • Default: true
1558 • Type: Boolean
1560 Set to false to suppress the update notification when using an older
1563 version of npm than the latest.
1564 usage
1566 • Default: false
1567 • Type: Boolean
1569 Show short usage output about the command specified.
1572 user-agent
1574 • Default: "npm/{npm-version} node/{node-version} {platform} {arch}
1575 workspaces/{workspaces} {ci}"
1576 • Type: String
1578 Sets the User-Agent request header. The following fields are replaced
1581 with their actual counterparts:
1582 • {npm-version} - The npm version in use
1584 • {node-version} - The Node.js version in use
1586 • {platform} - The value of process.platform
1588 • {arch} - The value of process.arch
1590 • {workspaces} - Set to true if the workspaces or workspace options are
1592 set.
1593 • {ci} - The value of the ci-name config, if set, prefixed with ci/, or
1595 an empty string if ci-name is empty.
1596 userconfig
1599 • Default: "~/.npmrc"
1600 • Type: Path
1602 The location of user-level configuration settings.
1605 This may be overridden by the npm_config_userconfig environment vari‐
1607 able or the --userconfig command line option, but may not be overridden
1608 by settings in the globalconfig file.
1609 version
1611 • Default: false
1612 • Type: Boolean
1614 If true, output the npm version and exit successfully.
1617 Only relevant when specified explicitly on the command line.
1619 versions
1621 • Default: false
1622 • Type: Boolean
1624 If true, output the npm version as well as node's process.versions map
1627 and the version in the current working directory's package.json file if
1628 one exists, and exit successfully.
1629 Only relevant when specified explicitly on the command line.
1631 viewer
1633 • Default: "man" on Posix, "browser" on Windows
1634 • Type: String
1636 The program to use to view help content.
1639 Set to "browser" to view html help content in the default web browser.
1641 which
1643 • Default: null
1644 • Type: null or Number
1646 If there are multiple funding sources, which 1-indexed source URL to
1649 open.
1650 workspace
1652 • Default:
1653 • Type: String (can be set multiple times)
1655 Enable running a command in the context of the configured workspaces of
1658 the current project while filtering by running only the workspaces de‐
1659 fined by this configuration option.
1660 Valid values for the workspace config are either:
1662 • Workspace names
1664 • Path to a workspace directory
1666 • Path to a parent workspace directory (will result in selecting all
1668 workspaces within that folder)
1669 When set for the npm init command, this may be set to the folder of a
1672 workspace which does not yet exist, to create the folder and set it up
1673 as a brand new workspace within the project.
1674 This value is not exported to the environment for child processes.
1676 workspaces
1678 • Default: null
1679 • Type: null or Boolean
1681 Set to true to run the command in the context of all configured
1684 workspaces.
1685 Explicitly setting this to false will cause commands like install to
1687 ignore workspaces altogether. When not set explicitly:
1688 • Commands that operate on the node_modules tree (install, update,
1690 etc.) will link workspaces into the node_modules folder. - Commands
1691 that do other things (test, exec, publish, etc.) will operate on the
1692 root project, unless one or more workspaces are specified in the
1693 workspace config.
1694 This value is not exported to the environment for child processes.
1697 workspaces-update
1699 • Default: true
1700 • Type: Boolean
1702 If set to true, the npm cli will run an update after operations that
1705 may possibly change the workspaces installed to the node_modules
1706 folder.
1707 yes
1709 • Default: null
1710 • Type: null or Boolean
1712 Automatically answer "yes" to any prompts that npm might print on the
1715 command line.
1716 also
1718 • Default: null
1719 • Type: null, "dev", or "development"
1721 • DEPRECATED: Please use --include=dev instead.
1723 When set to dev or development, this is an alias for --include=dev.
1726 cache-max
1728 • Default: Infinity
1729 • Type: Number
1731 • DEPRECATED: This option has been deprecated in favor of --prefer-on‐
1733 line
1734 --cache-max=0 is an alias for --prefer-online
1737 cache-min
1739 • Default: 0
1740 • Type: Number
1742 • DEPRECATED: This option has been deprecated in favor of --prefer-off‐
1744 line.
1745 --cache-min=9999 (or bigger) is an alias for --prefer-offline.
1748 dev
1750 • Default: false
1751 • Type: Boolean
1753 • DEPRECATED: Please use --include=dev instead.
1755 Alias for --include=dev.
1758 init.author.email
1760 • Default: ""
1761 • Type: String
1763 • DEPRECATED: Use --init-author-email instead.
1765 Alias for --init-author-email
1768 init.author.name
1770 • Default: ""
1771 • Type: String
1773 • DEPRECATED: Use --init-author-name instead.
1775 Alias for --init-author-name
1778 init.author.url
1780 • Default: ""
1781 • Type: "" or URL
1783 • DEPRECATED: Use --init-author-url instead.
1785 Alias for --init-author-url
1788 init.license
1790 • Default: "ISC"
1791 • Type: String
1793 • DEPRECATED: Use --init-license instead.
1795 Alias for --init-license
1798 init.module
1800 • Default: "~/.npm-init.js"
1801 • Type: Path
1803 • DEPRECATED: Use --init-module instead.
1805 Alias for --init-module
1808 init.version
1810 • Default: "1.0.0"
1811 • Type: SemVer string
1813 • DEPRECATED: Use --init-version instead.
1815 Alias for --init-version
1818 only
1820 • Default: null
1821 • Type: null, "prod", or "production"
1823 • DEPRECATED: Use --omit=dev to omit dev dependencies from the install.
1825 When set to prod or production, this is an alias for --omit=dev.
1828 optional
1830 • Default: null
1831 • Type: null or Boolean
1833 • DEPRECATED: Use --omit=optional to exclude optional dependencies, or
1835 --include=optional to include them.
1836 Default value does install optional deps unless otherwise omitted.
1839 Alias for --include=optional or --omit=optional
1841 production
1843 • Default: null
1844 • Type: null or Boolean
1846 • DEPRECATED: Use --omit=dev instead.
1848 Alias for --omit=dev
1851 shrinkwrap
1853 • Default: true
1854 • Type: Boolean
1856 • DEPRECATED: Use the --package-lock setting instead.
1858 Alias for --package-lock
1861 sso-poll-frequency
1863 • Default: 500
1864 • Type: Number
1866 • DEPRECATED: The --auth-type method of SSO/SAML/OAuth will be removed
1868 in a future version of npm in favor of web-based login.
1869 When used with SSO-enabled auth-types, configures how regularly the
1872 registry should be polled while the user is completing authentication.
1873 sso-type
1875 • Default: "oauth"
1876 • Type: null, "oauth", or "saml"
1878 • DEPRECATED: The --auth-type method of SSO/SAML/OAuth will be removed
1880 in a future version of npm in favor of web-based login.
1881 If --auth-type=sso, the type of SSO type to use.
1884 tmp
1886 • Default: The value returned by the Node.js os.tmpdir() method
1887 https://nodejs.org/api/os.html#os_os_tmpdir
1888 • Type: Path
1890 • DEPRECATED: This setting is no longer used. npm stores temporary
1892 files in a special location in the cache, and they are managed by ca‐
1893 cache http://npm.im/cacache.
1894 Historically, the location where temporary files were stored. No longer
1897 relevant.
1898 See also
1900 • npm help config
1901 • npm help npmrc
1903 • npm help scripts
1905 • npm help folders
1907 • npm help npm
1909 September 2022 CONFIG(7)