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 param‐
21 eters 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, so
29 NPM_CONFIG_FOO=bar will work the same. However, please note that inside
30 npm help scripts npm will set its own environment variables and Node
31 will prefer those lowercase versions over any uppercase ones that you
32 might set. For details see this issue ⟨https://github.com/npm/npm/is‐
33 sues/14528⟩.
34 Notice that you need to use underscores instead of dashes, so --allow-
36 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_CON‐
45 FIG_USERCONFIG)
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 registry.
170 For other registries you will need to scope it like "//other-reg‐
171 istry.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: 'public' for new packages, existing packages it will not
179 change the current level
180 • Type: null, "restricted", or "public"
182 If you do not want your scoped package to be publicly viewable (and in‐
185 stallable) set --access=restricted.
186 Unscoped packages can not be set to restricted.
188 Note: This defaults to not changing the current access level for exist‐
190 ing packages. Specifying a value of restricted or public during publish
191 will change the access for an existing package the same way that npm
192 access set status would.
193 all
195 • Default: false
196 • Type: Boolean
198 When running npm outdated and npm ls, setting --all will show all out‐
201 dated or installed packages, rather than only those directly depended
202 upon by the current project.
203 allow-same-version
205 • Default: false
206 • Type: Boolean
208 Prevents throwing an error when npm version is used to set the new ver‐
211 sion to the same value as the current version.
212 audit
214 • Default: true
215 • Type: Boolean
217 When "true" submit audit reports alongside the current npm command to
220 the default registry and all registries configured for scopes. See the
221 documentation for npm help audit for details on what is submitted.
222 audit-level
224 • Default: null
225 • Type: null, "info", "low", "moderate", "high", "critical", or
227 "none"
228 The minimum level of vulnerability for npm audit to exit with a non-
231 zero exit code.
232 auth-type
234 • Default: "web"
235 • Type: "legacy" or "web"
237 What authentication strategy to use with login. Note that if an otp
240 config is given, this value will always be set to legacy.
241 before
243 • Default: null
244 • Type: null or Date
246 If passed to npm install, will rebuild the npm tree such that only ver‐
249 sions that were available on or before the --before time get installed.
250 If there's no versions available for the current set of direct depen‐
251 dencies, the command will error.
252 If the requested version is a dist-tag and the given tag does not pass
254 the --before filter, the most recent version less than or equal to that
255 tag will be used. For example, foo@latest might install foo@1.2 even
256 though latest is 2.0.
257 bin-links
259 • Default: true
260 • Type: Boolean
262 Tells npm to create symlinks (or .cmd shims on Windows) for package ex‐
265 ecutables.
266 Set to false to have it not do this. This can be used to work around
268 the fact that some file systems don't support symlinks, even on osten‐
269 sibly Unix systems.
270 browser
272 • Default: OS X: "open", Windows: "start", Others: "xdg-open"
273 • Type: null, Boolean, or String
275 The browser that is called by npm commands to open websites.
278 Set to false to suppress browser behavior and instead print urls to
280 terminal.
281 Set to true to use default system URL opener.
283 ca
285 • Default: null
286 • Type: null or String (can be set multiple times)
288 The Certificate Authority signing certificate that is trusted for SSL
291 connections to the registry. Values should be in PEM format (Windows
292 calls it "Base-64 encoded X.509 (.CER)") with newlines replaced by the
293 string "\n". For example:
294 ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"
296 Set to null to only allow "known" registrars, or to a specific CA cert
298 to trust only that specific signing authority.
299 Multiple CAs can be trusted by specifying an array of certificates:
301 ca[]="..."
303 ca[]="..."
304 See also the strict-ssl config.
306 cache
308 • Default: Windows: %LocalAppData%\npm-cache, Posix: ~/.npm
309 • Type: Path
311 The location of npm's cache directory.
314 cafile
316 • Default: null
317 • Type: Path
319 A path to a file containing one or multiple Certificate Authority sign‐
322 ing certificates. Similar to the ca setting, but allows for multiple
323 CA's, as well as for the CA information to be stored in a file on disk.
324 call
326 • Default: ""
327 • Type: String
329 Optional companion option for npm exec, npx that allows for specifying
332 a custom command to be run along with the installed packages.
333 npm exec --package yo --package generator-node --call "yo node"
335 cidr
337 • Default: null
338 • Type: null or String (can be set multiple times)
340 This is a list of CIDR address to be used when configuring limited ac‐
343 cess tokens with the npm token create command.
344 color
346 • Default: true unless the NO_COLOR environ is set to something other
347 than '0'
348 • Type: "always" or Boolean
350 If false, never shows colors. If "always" then always shows colors. If
353 true, then only prints color codes for tty file descriptors.
354 commit-hooks
356 • Default: true
357 • Type: Boolean
359 Run git commit hooks when using the npm version command.
362 cpu
364 • Default: null
365 • Type: null or String
367 Override CPU architecture of native modules to install. Acceptable val‐
370 ues are same as cpu field of package.json, which comes from
371 process.arch.
372 depth
374 • Default: Infinity if --all is set, otherwise 1
375 • Type: null or Number
377 The depth to go when recursing packages for npm ls.
380 If not set, npm ls will show only the immediate dependencies of the
382 root project. If --all is set, then npm will show all dependencies by
383 default.
384 description
386 • Default: true
387 • Type: Boolean
389 Show the description in npm search
392 diff
394 • Default:
395 • Type: String (can be set multiple times)
397 Define arguments to compare in npm diff.
400 diff-dst-prefix
402 • Default: "b/"
403 • Type: String
405 Destination prefix to be used in npm diff output.
408 diff-ignore-all-space
410 • Default: false
411 • Type: Boolean
413 Ignore whitespace when comparing lines in npm diff.
416 diff-name-only
418 • Default: false
419 • Type: Boolean
421 Prints only filenames when using npm diff.
424 diff-no-prefix
426 • Default: false
427 • Type: Boolean
429 Do not show any source or destination prefix in npm diff output.
432 Note: this causes npm diff to ignore the --diff-src-prefix and --diff-
434 dst-prefix configs.
435 diff-src-prefix
437 • Default: "a/"
438 • Type: String
440 Source prefix to be used in npm diff output.
443 diff-text
445 • Default: false
446 • Type: Boolean
448 Treat all files as text in npm diff.
451 diff-unified
453 • Default: 3
454 • Type: Number
456 The number of lines of context to print in npm diff.
459 dry-run
461 • Default: false
462 • Type: Boolean
464 Indicates that you don't want npm to make any changes and that it
467 should only report what it would have done. This can be passed into any
468 of the commands that modify your local installation, eg, install, up‐
469 date, dedupe, uninstall, as well as pack and publish.
470 Note: This is NOT honored by other network related commands, eg dist-
472 tags, owner, etc.
473 editor
475 • Default: The EDITOR or VISUAL environment variables, or '%SYSTEM‐
476 ROOT%\notepad.exe' on Windows, or 'vi' on Unix systems
477 • Type: String
479 The command to run for npm edit and npm config edit.
482 engine-strict
484 • Default: false
485 • Type: Boolean
487 If set to true, then npm will stubbornly refuse to install (or even
490 consider installing) any package that claims to not be compatible with
491 the current Node.js version.
492 This can be overridden by setting the --force flag.
494 fetch-retries
496 • Default: 2
497 • Type: Number
499 The "retries" config for the retry module to use when fetching packages
502 from the registry.
503 npm will retry idempotent read requests to the registry in the case of
505 network failures or 5xx HTTP errors.
506 fetch-retry-factor
508 • Default: 10
509 • Type: Number
511 The "factor" config for the retry module to use when fetching packages.
514 fetch-retry-maxtimeout
516 • Default: 60000 (1 minute)
517 • Type: Number
519 The "maxTimeout" config for the retry module to use when fetching pack‐
522 ages.
523 fetch-retry-mintimeout
525 • Default: 10000 (10 seconds)
526 • Type: Number
528 The "minTimeout" config for the retry module to use when fetching pack‐
531 ages.
532 fetch-timeout
534 • Default: 300000 (5 minutes)
535 • Type: Number
537 The maximum amount of time to wait for HTTP requests to complete.
540 force
542 • Default: false
543 • Type: Boolean
545 Removes various protections against unfortunate side effects, common
548 mistakes, unnecessary performance degradation, and malicious input.
549 • Allow clobbering non-npm files in global installs.
551 • Allow the npm version command to work on an unclean git repository.
553 • Allow deleting the cache folder with npm cache clean.
555 • Allow installing packages that have an engines declaration requir‐
557 ing a different version of npm.
558 • Allow installing packages that have an engines declaration requir‐
560 ing a different version of node, even if --engine-strict is en‐
561 abled.
562 • Allow npm audit fix to install modules outside your stated depen‐
564 dency range (including SemVer-major changes).
565 • Allow unpublishing all versions of a published package.
567 • Allow conflicting peerDependencies to be installed in the root
569 project.
570 • Implicitly set --yes during npm init.
572 • Allow clobbering existing values in npm pkg
574 • Allow unpublishing of entire packages (not just a single version).
576 If you don't have a clear idea of what you want to do, it is strongly
579 recommended that you do not use this option!
580 foreground-scripts
582 • Default: false
583 • Type: Boolean
585 Run all build scripts (ie, preinstall, install, and postinstall)
588 scripts for installed packages in the foreground process, sharing stan‐
589 dard input, output, and error with the main npm process.
590 Note that this will generally make installs run slower, and be much
592 noisier, but can be useful for debugging.
593 format-package-lock
595 • Default: true
596 • Type: Boolean
598 Format package-lock.json or npm-shrinkwrap.json as a human readable
601 file.
602 fund
604 • Default: true
605 • Type: Boolean
607 When "true" displays the message at the end of each npm install ac‐
610 knowledging the number of dependencies looking for funding. See npm
611 help fund for details.
612 git
614 • Default: "git"
615 • Type: String
617 The command to use for git commands. If git is installed on the com‐
620 puter, but is not in the PATH, then set this to the full path to the
621 git binary.
622 git-tag-version
624 • Default: true
625 • Type: Boolean
627 Tag the commit when using the npm version command. Setting this to
630 false results in no commit being made at all.
631 global
633 • Default: false
634 • Type: Boolean
636 Operates in "global" mode, so that packages are installed into the pre‐
639 fix folder instead of the current working directory. See npm help fold‐
640 ers for more on the differences in behavior.
641 • packages are installed into the {prefix}/lib/node_modules folder,
643 instead of the current working directory.
644 • bin files are linked to {prefix}/bin
646 • man pages are linked to {prefix}/share/man
648 globalconfig
651 • Default: The global --prefix setting plus 'etc/npmrc'. For example,
652 '/usr/local/etc/npmrc'
653 • Type: Path
655 The config file to read for global config options.
658 heading
660 • Default: "npm"
661 • Type: String
663 The string that starts all the debugging log output.
666 https-proxy
668 • Default: null
669 • Type: null or URL
671 A proxy to use for outgoing https requests. If the HTTPS_PROXY or
674 https_proxy or HTTP_PROXY or http_proxy environment variables are set,
675 proxy settings will be honored by the underlying make-fetch-happen li‐
676 brary.
677 if-present
679 • Default: false
680 • Type: Boolean
682 If true, npm will not exit with an error code when run-script is in‐
685 voked for a script that isn't defined in the scripts section of pack‐
686 age.json. This option can be used when it's desirable to optionally run
687 a script when it's present and fail if the script fails. This is use‐
688 ful, for example, when running scripts that may only apply for some
689 builds in an otherwise generic CI setup.
690 This value is not exported to the environment for child processes.
692 ignore-scripts
694 • Default: false
695 • Type: Boolean
697 If true, npm does not run scripts specified in package.json files.
700 Note that commands explicitly intended to run a particular script, such
702 as npm start, npm stop, npm restart, npm test, and npm run-script will
703 still run their intended script if ignore-scripts is set, but they will
704 not run any pre- or post-scripts.
705 include
707 • Default:
708 • Type: "prod", "dev", "optional", or "peer" (can be set multiple
710 times)
711 Option that allows for defining which types of dependencies to install.
714 This is the inverse of --omit=<type>.
716 Dependency types specified in --include will not be omitted, regardless
718 of the order in which omit/include are specified on the command-line.
719 include-staged
721 • Default: false
722 • Type: Boolean
724 Allow installing "staged" published packages, as defined by npm RFC PR
727 #92 ⟨https://github.com/npm/rfcs/pull/92⟩.
728 This is experimental, and not implemented by the npm public registry.
730 include-workspace-root
732 • Default: false
733 • Type: Boolean
735 Include the workspace root when workspaces are enabled for a command.
738 When false, specifying individual workspaces via the workspace config,
740 or all workspaces via the workspaces flag, will cause npm to operate
741 only on the specified workspaces, and not on the root project.
742 This value is not exported to the environment for child processes.
744 init-author-email
746 • Default: ""
747 • Type: String
749 The value npm init should use by default for the package author's
752 email.
753 init-author-name
755 • Default: ""
756 • Type: String
758 The value npm init should use by default for the package author's name.
761 init-author-url
763 • Default: ""
764 • Type: "" or URL
766 The value npm init should use by default for the package author's home‐
769 page.
770 init-license
772 • Default: "ISC"
773 • Type: String
775 The value npm init should use by default for the package license.
778 init-module
780 • Default: "~/.npm-init.js"
781 • Type: Path
783 A module that will be loaded by the npm init command. See the documen‐
786 tation for the init-package-json ⟨https://github.com/npm/init-package-
787 json⟩ module for more information, or npm help init.
788 init-version
790 • Default: "1.0.0"
791 • Type: SemVer string
793 The value that npm init should use by default for the package version
796 number, if not already set in package.json.
797 install-links
799 • Default: false
800 • Type: Boolean
802 When set file: protocol dependencies will be packed and installed as
805 regular dependencies instead of creating a symlink. This option has no
806 effect on workspaces.
807 install-strategy
809 • Default: "hoisted"
810 • Type: "hoisted", "nested", "shallow", or "linked"
812 Sets the strategy for installing packages in node_modules. hoisted (de‐
815 fault): Install non-duplicated in top-level, and duplicated as neces‐
816 sary within directory structure. nested: (formerly --legacy-bundling)
817 install in place, no hoisting. shallow (formerly --global-style) only
818 install direct deps at top-level. linked: (experimental) install in
819 node_modules/.store, link in place, unhoisted.
820 json
822 • Default: false
823 • Type: Boolean
825 Whether or not to output JSON data, rather than the normal output.
828 • In npm pkg set it enables parsing set values with JSON.parse() be‐
830 fore saving them to your package.json.
831 Not supported by all npm commands.
834 legacy-peer-deps
836 • Default: false
837 • Type: Boolean
839 Causes npm to completely ignore peerDependencies when building a pack‐
842 age tree, as in npm versions 3 through 6.
843 If a package cannot be installed because of overly strict peerDependen‐
845 cies that collide, it provides a way to move forward resolving the sit‐
846 uation.
847 This differs from --omit=peer, in that --omit=peer will avoid unpacking
849 peerDependencies on disk, but will still design a tree such that
850 peerDependencies could be unpacked in a correct place.
851 Use of legacy-peer-deps is not recommended, as it will not enforce the
853 peerDependencies contract that meta-dependencies may rely on.
854 link
856 • Default: false
857 • Type: Boolean
859 Used with npm ls, limiting output to only those packages that are
862 linked.
863 local-address
865 • Default: null
866 • Type: IP Address
868 The IP address of the local interface to use when making connections to
871 the npm registry. Must be IPv4 in versions of Node prior to 0.12.
872 location
874 • Default: "user" unless --global is passed, which will also set this
875 value to "global"
876 • Type: "global", "user", or "project"
878 When passed to npm config this refers to which config file to use.
881 When set to "global" mode, packages are installed into the prefix
883 folder instead of the current working directory. See npm help folders
884 for more on the differences in behavior.
885 • packages are installed into the {prefix}/lib/node_modules folder,
887 instead of the current working directory.
888 • bin files are linked to {prefix}/bin
890 • man pages are linked to {prefix}/share/man
892 lockfile-version
895 • Default: Version 3 if no lockfile, auto-converting v1 lockfiles to
896 v3, otherwise maintain current lockfile version.
897 • Type: null, 1, 2, 3, "1", "2", or "3"
899 Set the lockfile format version to be used in package-lock.json and
902 npm-shrinkwrap-json files. Possible options are:
903 1: The lockfile version used by npm versions 5 and 6. Lacks some data
905 that is used during the install, resulting in slower and possibly less
906 deterministic installs. Prevents lockfile churn when interoperating
907 with older npm versions.
908 2: The default lockfile version used by npm version 7 and 8. Includes
910 both the version 1 lockfile data and version 3 lockfile data, for maxi‐
911 mum determinism and interoperability, at the expense of more bytes on
912 disk.
913 3: Only the new lockfile information introduced in npm version 7.
915 Smaller on disk than lockfile version 2, but not interoperable with
916 older npm versions. Ideal if all users are on npm version 7 and higher.
917 loglevel
919 • Default: "notice"
920 • Type: "silent", "error", "warn", "notice", "http", "info", "ver‐
922 bose", or "silly"
923 What level of logs to report. All logs are written to a debug log, with
926 the path to that file printed if the execution of a command fails.
927 Any logs of a higher level than the setting are shown. The default is
929 "notice".
930 See also the foreground-scripts config.
932 logs-dir
934 • Default: A directory named _logs inside the cache
935 • Type: null or Path
937 The location of npm's log directory. See npm help logging for more in‐
940 formation.
941 logs-max
943 • Default: 10
944 • Type: Number
946 The maximum number of log files to store.
949 If set to 0, no log files will be written for the current run.
951 long
953 • Default: false
954 • Type: Boolean
956 Show extended information in ls, search, and help-search.
959 maxsockets
961 • Default: 15
962 • Type: Number
964 The maximum number of connections to use per origin (protocol/host/port
967 combination).
968 message
970 • Default: "%s"
971 • Type: String
973 Commit message which is used by npm version when creating version com‐
976 mit.
977 Any "%s" in the message will be replaced with the version number.
979 node-options
981 • Default: null
982 • Type: null or String
984 Options to pass through to Node.js via the NODE_OPTIONS environment
987 variable. This does not impact how npm itself is executed but it does
988 impact how lifecycle scripts are called.
989 noproxy
991 • Default: The value of the NO_PROXY environment variable
992 • Type: String (can be set multiple times)
994 Domain extensions that should bypass any proxies.
997 Also accepts a comma-delimited string.
999 offline
1001 • Default: false
1002 • Type: Boolean
1004 Force offline mode: no network requests will be done during install. To
1007 allow the CLI to fill in missing cache data, see --prefer-offline.
1008 omit
1010 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
1011 duction', otherwise empty.
1012 • Type: "dev", "optional", or "peer" (can be set multiple times)
1014 Dependency types to omit from the installation tree on disk.
1017 Note that these dependencies are still resolved and added to the pack‐
1019 age-lock.json or npm-shrinkwrap.json file. They are just not physically
1020 installed on disk.
1021 If a package type appears in both the --include and --omit lists, then
1023 it will be included.
1024 If the resulting omit list includes 'dev', then the NODE_ENV environ‐
1026 ment variable will be set to 'production' for all lifecycle scripts.
1027 omit-lockfile-registry-resolved
1029 • Default: false
1030 • Type: Boolean
1032 This option causes npm to create lock files without a resolved key for
1035 registry dependencies. Subsequent installs will need to resolve tarball
1036 endpoints with the configured registry, likely resulting in a longer
1037 install time.
1038 os
1040 • Default: null
1041 • Type: null or String
1043 Override OS of native modules to install. Acceptable values are same as
1046 os field of package.json, which comes from process.platform.
1047 otp
1049 • Default: null
1050 • Type: null or String
1052 This is a one-time password from a two-factor authenticator. It's
1055 needed when publishing or changing package permissions with npm access.
1056 If not set, and a registry response fails with a challenge for a one-
1058 time password, npm will prompt on the command line for one.
1059 pack-destination
1061 • Default: "."
1062 • Type: String
1064 Directory in which npm pack will save tarballs.
1067 package
1069 • Default:
1070 • Type: String (can be set multiple times)
1072 The package or packages to install for npm help exec
1075 package-lock
1077 • Default: true
1078 • Type: Boolean
1080 If set to false, then ignore package-lock.json files when installing.
1083 This will also prevent writing package-lock.json if save is true.
1084 package-lock-only
1086 • Default: false
1087 • Type: Boolean
1089 If set to true, the current operation will only use the package-
1092 lock.json, ignoring node_modules.
1093 For update this means only the package-lock.json will be updated, in‐
1095 stead of checking node_modules and downloading dependencies.
1096 For list this means the output will be based on the tree described by
1098 the package-lock.json, rather than the contents of node_modules.
1099 parseable
1101 • Default: false
1102 • Type: Boolean
1104 Output parseable results from commands that write to standard output.
1107 For npm search, this will be tab-separated table format.
1108 prefer-dedupe
1110 • Default: false
1111 • Type: Boolean
1113 Prefer to deduplicate packages if possible, rather than choosing a
1116 newer version of a dependency.
1117 prefer-offline
1119 • Default: false
1120 • Type: Boolean
1122 If true, staleness checks for cached data will be bypassed, but missing
1125 data will be requested from the server. To force full offline mode, use
1126 --offline.
1127 prefer-online
1129 • Default: false
1130 • Type: Boolean
1132 If true, staleness checks for cached data will be forced, making the
1135 CLI look for updates immediately even for fresh package data.
1136 prefix
1138 • Default: In global mode, the folder where the node executable is
1139 installed. Otherwise, the nearest parent folder containing either a
1140 package.json file or a node_modules folder.
1141 • Type: Path
1143 The location to install global items. If set on the command line, then
1146 it forces non-global commands to run in the specified folder.
1147 preid
1149 • Default: ""
1150 • Type: String
1152 The "prerelease identifier" to use as a prefix for the "prerelease"
1155 part of a semver. Like the rc in 1.2.0-rc.8.
1156 progress
1158 • Default: true unless running in a known CI system
1159 • Type: Boolean
1161 When set to true, npm will display a progress bar during time intensive
1164 operations, if process.stderr is a TTY.
1165 Set to false to suppress the progress bar.
1167 provenance
1169 • Default: false
1170 • Type: Boolean
1172 When publishing from a supported cloud CI/CD system, the package will
1175 be publicly linked to where it was built and published from.
1176 This config can not be used with: provenance-file
1178 provenance-file
1180 • Default: null
1181 • Type: Path
1183 When publishing, the provenance bundle at the given path will be used.
1186 This config can not be used with: provenance
1188 proxy
1190 • Default: null
1191 • Type: null, false, or URL
1193 A proxy to use for outgoing http requests. If the HTTP_PROXY or
1196 http_proxy environment variables are set, proxy settings will be hon‐
1197 ored by the underlying request library.
1198 read-only
1200 • Default: false
1201 • Type: Boolean
1203 This is used to mark a token as unable to publish when configuring lim‐
1206 ited access tokens with the npm token create command.
1207 rebuild-bundle
1209 • Default: true
1210 • Type: Boolean
1212 Rebuild bundled dependencies after installation.
1215 registry
1217 • Default: "https://registry.npmjs.org/"
1218 • Type: URL
1220 The base URL of the npm registry.
1223 replace-registry-host
1225 • Default: "npmjs"
1226 • Type: "npmjs", "never", "always", or String
1228 Defines behavior for replacing the registry host in a lockfile with the
1231 configured registry.
1232 The default behavior is to replace package dist URLs from the default
1234 registry (https://registry.npmjs.org) to the configured registry. If
1235 set to "never", then use the registry value. If set to "always", then
1236 replace the registry host with the configured host every time.
1237 You may also specify a bare hostname (e.g., "registry.npmjs.org").
1239 save
1241 • Default: true unless when using npm update where it defaults to
1242 false
1243 • Type: Boolean
1245 Save installed packages to a package.json file as dependencies.
1248 When used with the npm rm command, removes the dependency from pack‐
1250 age.json.
1251 Will also prevent writing to package-lock.json if set to false.
1253 save-bundle
1255 • Default: false
1256 • Type: Boolean
1258 If a package would be saved at install time by the use of --save,
1261 --save-dev, or --save-optional, then also put it in the bundleDependen‐
1262 cies list.
1263 Ignored if --save-peer is set, since peerDependencies cannot be bun‐
1265 dled.
1266 save-dev
1268 • Default: false
1269 • Type: Boolean
1271 Save installed packages to a package.json file as devDependencies.
1274 save-exact
1276 • Default: false
1277 • Type: Boolean
1279 Dependencies saved to package.json will be configured with an exact
1282 version rather than using npm's default semver range operator.
1283 save-optional
1285 • Default: false
1286 • Type: Boolean
1288 Save installed packages to a package.json file as optionalDependencies.
1291 save-peer
1293 • Default: false
1294 • Type: Boolean
1296 Save installed packages to a package.json file as peerDependencies
1299 save-prefix
1301 • Default: "^"
1302 • Type: String
1304 Configure how versions of packages installed to a package.json file via
1307 --save or --save-dev get prefixed.
1308 For example if a package has version 1.2.3, by default its version is
1310 set to ^1.2.3 which allows minor upgrades for that package, but after
1311 npm config set save-prefix='~' it would be set to ~1.2.3 which only al‐
1312 lows patch upgrades.
1313 save-prod
1315 • Default: false
1316 • Type: Boolean
1318 Save installed packages into dependencies specifically. This is useful
1321 if a package already exists in devDependencies or optionalDependencies,
1322 but you want to move it to be a non-optional production dependency.
1323 This is the default behavior if --save is true, and neither --save-dev
1325 or --save-optional are true.
1326 sbom-format
1328 • Default: null
1329 • Type: "cyclonedx" or "spdx"
1331 SBOM format to use when generating SBOMs.
1334 sbom-type
1336 • Default: "library"
1337 • Type: "library", "application", or "framework"
1339 The type of package described by the generated SBOM. For SPDX, this is
1342 the value for the primaryPackagePurpose fieled. For CycloneDX, this is
1343 the value for the type field.
1344 scope
1346 • Default: the scope of the current project, if any, or ""
1347 • Type: String
1349 Associate an operation with a scope for a scoped registry.
1352 Useful when logging in to or out of a private registry:
1354 # log in, linking the scope to the custom registry
1356 npm login --scope=@mycorp --registry=https://registry.mycorp.com
1357 # log out, removing the link and the auth token
1359 npm logout --scope=@mycorp
1360 This will cause @mycorp to be mapped to the registry for future instal‐
1362 lation of packages specified according to the pattern @mycorp/package.
1363 This will also cause npm init to create a scoped package.
1365 # accept all defaults, and create a package named "@foo/whatever",
1367 # instead of just named "whatever"
1368 npm init --scope=@foo --yes
1369 script-shell
1371 • Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows
1372 • Type: null or String
1374 The shell to use for scripts run with the npm exec, npm run and npm
1377 init <package-spec> commands.
1378 searchexclude
1380 • Default: ""
1381 • Type: String
1383 Space-separated options that limit the results from search.
1386 searchlimit
1388 • Default: 20
1389 • Type: Number
1391 Number of items to limit search results to. Will not apply at all to
1394 legacy searches.
1395 searchopts
1397 • Default: ""
1398 • Type: String
1400 Space-separated options that are always passed to search.
1403 searchstaleness
1405 • Default: 900
1406 • Type: Number
1408 The age of the cache, in seconds, before another registry request is
1411 made if using legacy search endpoint.
1412 shell
1414 • Default: SHELL environment variable, or "bash" on Posix, or
1415 "cmd.exe" on Windows
1416 • Type: String
1418 The shell to run for the npm explore command.
1421 sign-git-commit
1423 • Default: false
1424 • Type: Boolean
1426 If set to true, then the npm version command will commit the new pack‐
1429 age version using -S to add a signature.
1430 Note that git requires you to have set up GPG keys in your git configs
1432 for this to work properly.
1433 sign-git-tag
1435 • Default: false
1436 • Type: Boolean
1438 If set to true, then the npm version command will tag the version using
1441 -s to add a signature.
1442 Note that git requires you to have set up GPG keys in your git configs
1444 for this to work properly.
1445 strict-peer-deps
1447 • Default: false
1448 • Type: Boolean
1450 If set to true, and --legacy-peer-deps is not set, then any conflicting
1453 peerDependencies will be treated as an install failure, even if npm
1454 could reasonably guess the appropriate resolution based on non-peer de‐
1455 pendency relationships.
1456 By default, conflicting peerDependencies deep in the dependency graph
1458 will be resolved using the nearest non-peer dependency specification,
1459 even if doing so will result in some packages receiving a peer depen‐
1460 dency outside the range set in their package's peerDependencies object.
1461 When such an override is performed, a warning is printed, explaining
1463 the conflict and the packages involved. If --strict-peer-deps is set,
1464 then this warning is treated as a failure.
1465 strict-ssl
1467 • Default: true
1468 • Type: Boolean
1470 Whether or not to do SSL key validation when making requests to the
1473 registry via https.
1474 See also the ca config.
1476 tag
1478 • Default: "latest"
1479 • Type: String
1481 If you ask npm to install a package and don't tell it a specific ver‐
1484 sion, then it will install the specified tag.
1485 Also the tag that is added to the package@version specified by the npm
1487 tag command, if no explicit tag is given.
1488 When used by the npm diff command, this is the tag used to fetch the
1490 tarball that will be compared with the local files by default.
1491 tag-version-prefix
1493 • Default: "v"
1494 • Type: String
1496 If set, alters the prefix used when tagging a new version when perform‐
1499 ing a version increment using npm version. To remove the prefix alto‐
1500 gether, set it to the empty string: "".
1501 Because other tools may rely on the convention that npm version tags
1503 look like v1.0.0, only use this property if it is absolutely necessary.
1504 In particular, use care when overriding this setting for public pack‐
1505 ages.
1506 timing
1508 • Default: false
1509 • Type: Boolean
1511 If true, writes timing information to a process specific json file in
1514 the cache or logs-dir. The file name ends with -timing.json.
1515 You can quickly view it with this json ⟨https://npm.im/json⟩ command
1517 line: cat ~/.npm/_logs/*-timing.json | npm exec -- json -g.
1518 Timing information will also be reported in the terminal. To suppress
1520 this while still writing the timing file, use --silent.
1521 umask
1523 • Default: 0
1524 • Type: Octal numeric string in range 0000..0777 (0..511)
1526 The "umask" value to use when setting the file creation mode on files
1529 and folders.
1530 Folders and executables are given a mode which is 0o777 masked against
1532 this value. Other files are given a mode which is 0o666 masked against
1533 this value.
1534 Note that the underlying system will also apply its own umask value to
1536 files and folders that are created, and npm does not circumvent this,
1537 but rather adds the --umask config to it.
1538 Thus, the effective default umask value on most POSIX systems is 0o22,
1540 meaning that folders and executables are created with a mode of 0o755
1541 and other files are created with a mode of 0o644.
1542 unicode
1544 • Default: false on windows, true on mac/unix systems with a unicode
1545 locale, as defined by the LC_ALL, LC_CTYPE, or LANG environment
1546 variables.
1547 • Type: Boolean
1549 When set to true, npm uses unicode characters in the tree output. When
1552 false, it uses ascii characters instead of unicode glyphs.
1553 update-notifier
1555 • Default: true
1556 • Type: Boolean
1558 Set to false to suppress the update notification when using an older
1561 version of npm than the latest.
1562 usage
1564 • Default: false
1565 • Type: Boolean
1567 Show short usage output about the command specified.
1570 user-agent
1572 • Default: "npm/{npm-version} node/{node-version} {platform} {arch}
1573 workspaces/{workspaces} {ci}"
1574 • Type: String
1576 Sets the User-Agent request header. The following fields are replaced
1579 with their actual counterparts:
1580 • {npm-version} - The npm version in use
1582 • {node-version} - The Node.js version in use
1584 • {platform} - The value of process.platform
1586 • {arch} - The value of process.arch
1588 • {workspaces} - Set to true if the workspaces or workspace options
1590 are set.
1591 • {ci} - The value of the ci-name config, if set, prefixed with ci/,
1593 or an empty string if ci-name is empty.
1594 userconfig
1597 • Default: "~/.npmrc"
1598 • Type: Path
1600 The location of user-level configuration settings.
1603 This may be overridden by the npm_config_userconfig environment vari‐
1605 able or the --userconfig command line option, but may not be overridden
1606 by settings in the globalconfig file.
1607 version
1609 • Default: false
1610 • Type: Boolean
1612 If true, output the npm version and exit successfully.
1615 Only relevant when specified explicitly on the command line.
1617 versions
1619 • Default: false
1620 • Type: Boolean
1622 If true, output the npm version as well as node's process.versions map
1625 and the version in the current working directory's package.json file if
1626 one exists, and exit successfully.
1627 Only relevant when specified explicitly on the command line.
1629 viewer
1631 • Default: "man" on Posix, "browser" on Windows
1632 • Type: String
1634 The program to use to view help content.
1637 Set to "browser" to view html help content in the default web browser.
1639 which
1641 • Default: null
1642 • Type: null or Number
1644 If there are multiple funding sources, which 1-indexed source URL to
1647 open.
1648 workspace
1650 • Default:
1651 • Type: String (can be set multiple times)
1653 Enable running a command in the context of the configured workspaces of
1656 the current project while filtering by running only the workspaces de‐
1657 fined by this configuration option.
1658 Valid values for the workspace config are either:
1660 • Workspace names
1662 • Path to a workspace directory
1664 • Path to a parent workspace directory (will result in selecting all
1666 workspaces within that folder)
1667 When set for the npm init command, this may be set to the folder of a
1670 workspace which does not yet exist, to create the folder and set it up
1671 as a brand new workspace within the project.
1672 This value is not exported to the environment for child processes.
1674 workspaces
1676 • Default: null
1677 • Type: null or Boolean
1679 Set to true to run the command in the context of all configured
1682 workspaces.
1683 Explicitly setting this to false will cause commands like install to
1685 ignore workspaces altogether. When not set explicitly:
1686 • Commands that operate on the node_modules tree (install, update,
1688 etc.) will link workspaces into the node_modules folder. - Commands
1689 that do other things (test, exec, publish, etc.) will operate on
1690 the root project, unless one or more workspaces are specified in
1691 the workspace config.
1692 This value is not exported to the environment for child processes.
1695 workspaces-update
1697 • Default: true
1698 • Type: Boolean
1700 If set to true, the npm cli will run an update after operations that
1703 may possibly change the workspaces installed to the node_modules
1704 folder.
1705 yes
1707 • Default: null
1708 • Type: null or Boolean
1710 Automatically answer "yes" to any prompts that npm might print on the
1713 command line.
1714 also
1716 • Default: null
1717 • Type: null, "dev", or "development"
1719 • DEPRECATED: Please use --include=dev instead.
1721 When set to dev or development, this is an alias for --include=dev.
1724 cache-max
1726 • Default: Infinity
1727 • Type: Number
1729 • DEPRECATED: This option has been deprecated in favor of --prefer-
1731 online
1732 --cache-max=0 is an alias for --prefer-online
1735 cache-min
1737 • Default: 0
1738 • Type: Number
1740 • DEPRECATED: This option has been deprecated in favor of --prefer-
1742 offline.
1743 --cache-min=9999 (or bigger) is an alias for --prefer-offline.
1746 cert
1748 • Default: null
1749 • Type: null or String
1751 • DEPRECATED: key and cert are no longer used for most registry oper‐
1753 ations. Use registry scoped keyfile and certfile instead. Example:
1754 //other-registry.tld/:keyfile=/path/to/key.pem //other-reg‐
1755 istry.tld/:certfile=/path/to/cert.crt
1756 A client certificate to pass when accessing the registry. Values should
1759 be in PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with
1760 newlines replaced by the string "\n". For example:
1761 cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"
1763 It is not the path to a certificate file, though you can set a reg‐
1765 istry-scoped "certfile" path like "//other-registry.tld/:cert‐
1766 file=/path/to/cert.pem".
1767 dev
1769 • Default: false
1770 • Type: Boolean
1772 • DEPRECATED: Please use --include=dev instead.
1774 Alias for --include=dev.
1777 global-style
1779 • Default: false
1780 • Type: Boolean
1782 • DEPRECATED: This option has been deprecated in favor of --install-
1784 strategy=shallow
1785 Only install direct dependencies in the top level node_modules, but
1788 hoist on deeper dependencies. Sets --install-strategy=shallow.
1789 init.author.email
1791 • Default: ""
1792 • Type: String
1794 • DEPRECATED: Use --init-author-email instead.
1796 Alias for --init-author-email
1799 init.author.name
1801 • Default: ""
1802 • Type: String
1804 • DEPRECATED: Use --init-author-name instead.
1806 Alias for --init-author-name
1809 init.author.url
1811 • Default: ""
1812 • Type: "" or URL
1814 • DEPRECATED: Use --init-author-url instead.
1816 Alias for --init-author-url
1819 init.license
1821 • Default: "ISC"
1822 • Type: String
1824 • DEPRECATED: Use --init-license instead.
1826 Alias for --init-license
1829 init.module
1831 • Default: "~/.npm-init.js"
1832 • Type: Path
1834 • DEPRECATED: Use --init-module instead.
1836 Alias for --init-module
1839 init.version
1841 • Default: "1.0.0"
1842 • Type: SemVer string
1844 • DEPRECATED: Use --init-version instead.
1846 Alias for --init-version
1849 key
1851 • Default: null
1852 • Type: null or String
1854 • DEPRECATED: key and cert are no longer used for most registry oper‐
1856 ations. Use registry scoped keyfile and certfile instead. Example:
1857 //other-registry.tld/:keyfile=/path/to/key.pem //other-reg‐
1858 istry.tld/:certfile=/path/to/cert.crt
1859 A client key to pass when accessing the registry. Values should be in
1862 PEM format with newlines replaced by the string "\n". For example:
1863 key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"
1865 It is not the path to a key file, though you can set a registry-scoped
1867 "keyfile" path like "//other-registry.tld/:keyfile=/path/to/key.pem".
1868 legacy-bundling
1870 • Default: false
1871 • Type: Boolean
1873 • DEPRECATED: This option has been deprecated in favor of --install-
1875 strategy=nested
1876 Instead of hoisting package installs in node_modules, install packages
1879 in the same manner that they are depended on. This may cause very deep
1880 directory structures and duplicate package installs as there is no de-
1881 duplicating. Sets --install-strategy=nested.
1882 only
1884 • Default: null
1885 • Type: null, "prod", or "production"
1887 • DEPRECATED: Use --omit=dev to omit dev dependencies from the in‐
1889 stall.
1890 When set to prod or production, this is an alias for --omit=dev.
1893 optional
1895 • Default: null
1896 • Type: null or Boolean
1898 • DEPRECATED: Use --omit=optional to exclude optional dependencies,
1900 or --include=optional to include them.
1901 Default value does install optional deps unless otherwise omitted.
1904 Alias for --include=optional or --omit=optional
1906 production
1908 • Default: null
1909 • Type: null or Boolean
1911 • DEPRECATED: Use --omit=dev instead.
1913 Alias for --omit=dev
1916 shrinkwrap
1918 • Default: true
1919 • Type: Boolean
1921 • DEPRECATED: Use the --package-lock setting instead.
1923 Alias for --package-lock
1926 See also
1928 • npm help config
1929 • npm help npmrc
1931 • npm help scripts
1933 • npm help folders
1935 • npm help npm
1937 November 2023 CONFIG(7)