codekingpro/portable-devtools
114k
1.TH "CONFIG" "7" "April 2026" "NPM@11.13.0" ""
2.SH "NAME"
3\fBConfig\fR - About npm configuration
4.SS "Description"
5.P
6This article details npm configuration in general. To learn about the \fBconfig\fR command, see npm help config.
7.P
8npm gets its configuration values from the following sources, sorted by priority:
9.SS "Command Line Flags"
10.P
11Putting \fB--foo bar\fR on the command line sets the \fBfoo\fR configuration parameter to \fB"bar"\fR. A \fB--\fR argument tells the cli parser to stop reading flags. Using \fB--flag\fR without specifying any value will set the value to \fBtrue\fR.
12.P
13Example: \fB--flag1 --flag2\fR will set both configuration parameters to \fBtrue\fR, while \fB--flag1 --flag2 bar\fR will set \fBflag1\fR to \fBtrue\fR, and \fBflag2\fR to \fBbar\fR. Finally, \fB--flag1 --flag2 -- bar\fR will set both configuration parameters to \fBtrue\fR, and the \fBbar\fR is taken as a command argument.
14.P
15\fBCommon examples:\fR
16.RS 0
17.IP \(bu 4
18\fBnpm install --prefix /path/to/dir\fR - Runs npm commands in a different directory without changing the current working directory
19.IP \(bu 4
20\fBnpm install --global\fR - Installs packages globally (shorthand: \fB-g\fR)
21.IP \(bu 4
22\fBnpm install --save-dev\fR - Saves to devDependencies (shorthand: \fB-D\fR)
23.RE 0
24
25.P
26Any configuration option documented in the \fI(Config Settings)\fR section below can be set via command line flags using \fB--option-name value\fR syntax.
27.SS "Environment Variables"
28.P
29Any environment variables that start with \fBnpm_config_\fR will be interpreted as a configuration parameter. For example, putting \fBnpm_config_foo=bar\fR in your environment will set the \fBfoo\fR configuration parameter to \fBbar\fR. Any environment configurations that are not given a value will be given the value of \fBtrue\fR. Config values are case-insensitive, so \fBNPM_CONFIG_FOO=bar\fR will work the same. However, please note that inside npm help scripts npm will set its own environment variables and Node will prefer those lowercase versions over any uppercase ones that you might set. For details see \fBthis issue\fR \fI\(lahttps://github.com/npm/npm/issues/14528\(ra\fR.
30.P
31Notice that you need to use underscores instead of dashes, so \fB--allow-same-version\fR would become \fBnpm_config_allow_same_version=true\fR.
32.P
33\fBImportant:\fR When defining custom configuration keys in \fB.npmrc\fR files, use hyphens instead of underscores (e.g., \fBcustom-key=value\fR). This ensures they can be overridden by environment variables, since npm automatically converts underscores to hyphens when reading environment variables. Keys with underscores in \fB.npmrc\fR files cannot be overridden via environment variables.
34.SS "npmrc Files"
35.P
36The four relevant files are:
37.RS 0
38.IP \(bu 4
39per-project configuration file (\fB/path/to/my/project/.npmrc\fR)
40.IP \(bu 4
41per-user configuration file (defaults to \fB$HOME/.npmrc\fR; configurable via CLI option \fB--userconfig\fR or environment variable \fB$NPM_CONFIG_USERCONFIG\fR)
42.IP \(bu 4
43global configuration file (defaults to \fB$PREFIX/etc/npmrc\fR; configurable via CLI option \fB--globalconfig\fR or environment variable \fB$NPM_CONFIG_GLOBALCONFIG\fR)
44.IP \(bu 4
45npm's built-in configuration file (\fB/path/to/npm/npmrc\fR)
46.RE 0
47
48.P
49See npm help npmrc for more details.
50.SS "Default Configs"
51.P
52Run \fBnpm config ls -l\fR to see a set of configuration parameters that are internal to npm, and are defaults if nothing else is specified.
53.SS "Shorthands and Other CLI Niceties"
54.P
55The following shorthands are parsed on the command-line:
56.RS 0
57.IP \(bu 4
58\fB-a\fR: \fB--all\fR
59.IP \(bu 4
60\fB--enjoy-by\fR: \fB--before\fR
61.IP \(bu 4
62\fB-c\fR: \fB--call\fR
63.IP \(bu 4
64\fB--desc\fR: \fB--description\fR
65.IP \(bu 4
66\fB-f\fR: \fB--force\fR
67.IP \(bu 4
68\fB-g\fR: \fB--global\fR
69.IP \(bu 4
70\fB--iwr\fR: \fB--include-workspace-root\fR
71.IP \(bu 4
72\fB-L\fR: \fB--location\fR
73.IP \(bu 4
74\fB-d\fR: \fB--loglevel info\fR
75.IP \(bu 4
76\fB-s\fR: \fB--loglevel silent\fR
77.IP \(bu 4
78\fB--silent\fR: \fB--loglevel silent\fR
79.IP \(bu 4
80\fB--ddd\fR: \fB--loglevel silly\fR
81.IP \(bu 4
82\fB--dd\fR: \fB--loglevel verbose\fR
83.IP \(bu 4
84\fB--verbose\fR: \fB--loglevel verbose\fR
85.IP \(bu 4
86\fB-q\fR: \fB--loglevel warn\fR
87.IP \(bu 4
88\fB--quiet\fR: \fB--loglevel warn\fR
89.IP \(bu 4
90\fB-l\fR: \fB--long\fR
91.IP \(bu 4
92\fB-m\fR: \fB--message\fR
93.IP \(bu 4
94\fB--local\fR: \fB--no-global\fR
95.IP \(bu 4
96\fB-n\fR: \fB--no-yes\fR
97.IP \(bu 4
98\fB--no\fR: \fB--no-yes\fR
99.IP \(bu 4
100\fB-p\fR: \fB--parseable\fR
101.IP \(bu 4
102\fB--porcelain\fR: \fB--parseable\fR
103.IP \(bu 4
104\fB-C\fR: \fB--prefix\fR
105.IP \(bu 4
106\fB--readonly\fR: \fB--read-only\fR
107.IP \(bu 4
108\fB--reg\fR: \fB--registry\fR
109.IP \(bu 4
110\fB-S\fR: \fB--save\fR
111.IP \(bu 4
112\fB-B\fR: \fB--save-bundle\fR
113.IP \(bu 4
114\fB-D\fR: \fB--save-dev\fR
115.IP \(bu 4
116\fB-E\fR: \fB--save-exact\fR
117.IP \(bu 4
118\fB-O\fR: \fB--save-optional\fR
119.IP \(bu 4
120\fB-P\fR: \fB--save-prod\fR
121.IP \(bu 4
122\fB-?\fR: \fB--usage\fR
123.IP \(bu 4
124\fB-h\fR: \fB--usage\fR
125.IP \(bu 4
126\fB-H\fR: \fB--usage\fR
127.IP \(bu 4
128\fB--help\fR: \fB--usage\fR
129.IP \(bu 4
130\fB-v\fR: \fB--version\fR
131.IP \(bu 4
132\fB-w\fR: \fB--workspace\fR
133.IP \(bu 4
134\fB--ws\fR: \fB--workspaces\fR
135.IP \(bu 4
136\fB-y\fR: \fB--yes\fR
137.RE 0
138
139.P
140If the specified configuration param resolves unambiguously to a known configuration parameter, then it is expanded to that configuration parameter. For example:
141.P
142.RS 2
143.nf
144npm ls --par
145# same as:
146npm ls --parseable
147.fi
148.RE
149.P
150If multiple single-character shorthands are strung together, and the resulting combination is unambiguously not some other configuration param, then it is expanded to its various component pieces. For example:
151.P
152.RS 2
153.nf
154npm ls -gpld
155# same as:
156npm ls --global --parseable --long --loglevel info
157.fi
158.RE
159.SS "Config Settings"
160.SS "\fB_auth\fR"
161.RS 0
162.IP \(bu 4
163Default: null
164.IP \(bu 4
165Type: null or String
166.RE 0
167
168.P
169A basic-auth string to use when authenticating against the npm registry. This will ONLY be used to authenticate against the npm registry. For other registries you will need to scope it like "//other-registry.tld/:_auth"
170.P
171Warning: This should generally not be set via a command-line option. It is safer to use a registry-provided authentication bearer token stored in the ~/.npmrc file by running \fBnpm login\fR.
172.SS "\fBaccess\fR"
173.RS 0
174.IP \(bu 4
175Default: 'public' for new packages, existing packages it will not change the current level
176.IP \(bu 4
177Type: null, "restricted", or "public"
178.RE 0
179
180.P
181If you do not want your scoped package to be publicly viewable (and installable) set \fB--access=restricted\fR.
182.P
183Unscoped packages cannot be set to \fBrestricted\fR.
184.P
185Note: This defaults to not changing the current access level for existing packages. Specifying a value of \fBrestricted\fR or \fBpublic\fR during publish will change the access for an existing package the same way that \fBnpm access set
186status\fR would.
187.SS "\fBall\fR"
188.RS 0
189.IP \(bu 4
190Default: false
191.IP \(bu 4
192Type: Boolean
193.RE 0
194
195.P
196When running \fBnpm outdated\fR and \fBnpm ls\fR, setting \fB--all\fR will show all outdated or installed packages, rather than only those directly depended upon by the current project.
197.SS "\fBallow-git\fR"
198.RS 0
199.IP \(bu 4
200Default: "all"
201.IP \(bu 4
202Type: "all", "none", or "root"
203.RE 0
204
205.P
206Limits the ability for npm to fetch dependencies from git references. That is, dependencies that point to a git repo instead of a version or semver range. Please note that this could leave your tree incomplete and some packages may not function as intended or designed.
207.P
208\fBall\fR allows any git dependencies to be fetched and installed. \fBnone\fR prevents any git dependencies from being fetched and installed. \fBroot\fR only allows git dependencies defined in your project's package.json to be fetched installed. Also allows git dependencies to be fetched for other commands like \fBnpm view\fR
209.SS "\fBallow-same-version\fR"
210.RS 0
211.IP \(bu 4
212Default: false
213.IP \(bu 4
214Type: Boolean
215.RE 0
216
217.P
218Prevents throwing an error when \fBnpm version\fR is used to set the new version to the same value as the current version.
219.SS "\fBaudit\fR"
220.RS 0
221.IP \(bu 4
222Default: true
223.IP \(bu 4
224Type: Boolean
225.RE 0
226
227.P
228When "true" submit audit reports alongside the current npm command to the default registry and all registries configured for scopes. See the documentation for npm help audit for details on what is submitted.
229.SS "\fBaudit-level\fR"
230.RS 0
231.IP \(bu 4
232Default: null
233.IP \(bu 4
234Type: null, "info", "low", "moderate", "high", "critical", or "none"
235.RE 0
236
237.P
238The minimum level of vulnerability for \fBnpm audit\fR to exit with a non-zero exit code.
239.SS "\fBauth-type\fR"
240.RS 0
241.IP \(bu 4
242Default: "web"
243.IP \(bu 4
244Type: "legacy" or "web"
245.RE 0
246
247.P
248What authentication strategy to use with \fBlogin\fR. Note that if an \fBotp\fR config is given, this value will always be set to \fBlegacy\fR.
249.SS "\fBbefore\fR"
250.RS 0
251.IP \(bu 4
252Default: null
253.IP \(bu 4
254Type: null or Date
255.RE 0
256
257.P
258If passed to \fBnpm install\fR, will rebuild the npm tree such that only versions that were available \fBon or before\fR the given date are installed. If there are no versions available for the current set of dependencies, the command will error.
259.P
260If the requested version is a \fBdist-tag\fR and the given tag does not pass the \fB--before\fR filter, the most recent version less than or equal to that tag will be used. For example, \fBfoo@latest\fR might install \fBfoo@1.2\fR even though \fBlatest\fR is \fB2.0\fR.
261.P
262This config cannot be used with: \fBmin-release-age\fR
263.SS "\fBbin-links\fR"
264.RS 0
265.IP \(bu 4
266Default: true
267.IP \(bu 4
268Type: Boolean
269.RE 0
270
271.P
272Tells npm to create symlinks (or \fB.cmd\fR shims on Windows) for package executables.
273.P
274Set to false to have it not do this. This can be used to work around the fact that some file systems don't support symlinks, even on ostensibly Unix systems.
275.SS "\fBbrowser\fR"
276.RS 0
277.IP \(bu 4
278Default: macOS: \fB"open"\fR, Windows: \fB"start"\fR, Others: \fB"xdg-open"\fR
279.IP \(bu 4
280Type: null, Boolean, or String
281.RE 0
282
283.P
284The browser that is called by npm commands to open websites.
285.P
286Set to \fBfalse\fR to suppress browser behavior and instead print urls to terminal.
287.P
288Set to \fBtrue\fR to use default system URL opener.
289.SS "\fBbypass-2fa\fR"
290.RS 0
291.IP \(bu 4
292Default: false
293.IP \(bu 4
294Type: Boolean
295.RE 0
296
297.P
298When creating a Granular Access Token with \fBnpm token create\fR, setting this to true will allow the token to bypass two-factor authentication. This is useful for automation and CI/CD workflows.
299.SS "\fBca\fR"
300.RS 0
301.IP \(bu 4
302Default: null
303.IP \(bu 4
304Type: null or String (can be set multiple times)
305.RE 0
306
307.P
308The Certificate Authority signing certificate that is trusted for SSL connections to the registry. Values should be in PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with newlines replaced by the string "\[rs]n". For example:
309.P
310.RS 2
311.nf
312ca="-----BEGIN CERTIFICATE-----\[rs]nXXXX\[rs]nXXXX\[rs]n-----END CERTIFICATE-----"
313.fi
314.RE
315.P
316Set to \fBnull\fR to only allow "known" registrars, or to a specific CA cert to trust only that specific signing authority.
317.P
318Multiple CAs can be trusted by specifying an array of certificates:
319.P
320.RS 2
321.nf
322ca\[lB]\[rB]="..."
323ca\[lB]\[rB]="..."
324.fi
325.RE
326.P
327See also the \fBstrict-ssl\fR config.
328.SS "\fBcache\fR"
329.RS 0
330.IP \(bu 4
331Default: Windows: \fB%LocalAppData%\[rs]npm-cache\fR, Posix: \fB~/.npm\fR
332.IP \(bu 4
333Type: Path
334.RE 0
335
336.P
337The location of npm's cache directory.
338.SS "\fBcafile\fR"
339.RS 0
340.IP \(bu 4
341Default: null
342.IP \(bu 4
343Type: Path
344.RE 0
345
346.P
347A path to a file containing one or multiple Certificate Authority signing certificates. Similar to the \fBca\fR setting, but allows for multiple CA's, as well as for the CA information to be stored in a file on disk.
348.SS "\fBcall\fR"
349.RS 0
350.IP \(bu 4
351Default: ""
352.IP \(bu 4
353Type: String
354.RE 0
355
356.P
357Optional companion option for \fBnpm exec\fR, \fBnpx\fR that allows for specifying a custom command to be run along with the installed packages.
358.P
359.RS 2
360.nf
361npm exec --package yo --package generator-node --call "yo node"
362.fi
363.RE
364.SS "\fBcidr\fR"
365.RS 0
366.IP \(bu 4
367Default: null
368.IP \(bu 4
369Type: null or String (can be set multiple times)
370.RE 0
371
372.P
373This is a list of CIDR address to be used when configuring limited access tokens with the \fBnpm token create\fR command.
374.SS "\fBcolor\fR"
375.RS 0
376.IP \(bu 4
377Default: true unless the NO_COLOR environ is set to something other than '0'
378.IP \(bu 4
379Type: "always" or Boolean
380.RE 0
381
382.P
383If false, never shows colors. If \fB"always"\fR then always shows colors. If true, then only prints color codes for tty file descriptors.
384.SS "\fBcommit-hooks\fR"
385.RS 0
386.IP \(bu 4
387Default: true
388.IP \(bu 4
389Type: Boolean
390.RE 0
391
392.P
393Run git commit hooks when using the \fBnpm version\fR command.
394.SS "\fBcpu\fR"
395.RS 0
396.IP \(bu 4
397Default: null
398.IP \(bu 4
399Type: null or String
400.RE 0
401
402.P
403Override CPU architecture of native modules to install. Acceptable values are same as \fBcpu\fR field of package.json, which comes from \fBprocess.arch\fR.
404.SS "\fBdepth\fR"
405.RS 0
406.IP \(bu 4
407Default: \fBInfinity\fR if \fB--all\fR is set; otherwise, \fB0\fR
408.IP \(bu 4
409Type: null or Number
410.RE 0
411
412.P
413The depth to go when recursing packages for \fBnpm ls\fR.
414.P
415If not set, \fBnpm ls\fR will show only the immediate dependencies of the root project. If \fB--all\fR is set, then npm will show all dependencies by default.
416.SS "\fBdescription\fR"
417.RS 0
418.IP \(bu 4
419Default: true
420.IP \(bu 4
421Type: Boolean
422.RE 0
423
424.P
425Show the description in \fBnpm search\fR
426.SS "\fBdiff\fR"
427.RS 0
428.IP \(bu 4
429Default:
430.IP \(bu 4
431Type: String (can be set multiple times)
432.RE 0
433
434.P
435Define arguments to compare in \fBnpm diff\fR.
436.SS "\fBdiff-dst-prefix\fR"
437.RS 0
438.IP \(bu 4
439Default: "b/"
440.IP \(bu 4
441Type: String
442.RE 0
443
444.P
445Destination prefix to be used in \fBnpm diff\fR output.
446.SS "\fBdiff-ignore-all-space\fR"
447.RS 0
448.IP \(bu 4
449Default: false
450.IP \(bu 4
451Type: Boolean
452.RE 0
453
454.P
455Ignore whitespace when comparing lines in \fBnpm diff\fR.
456.SS "\fBdiff-name-only\fR"
457.RS 0
458.IP \(bu 4
459Default: false
460.IP \(bu 4
461Type: Boolean
462.RE 0
463
464.P
465Prints only filenames when using \fBnpm diff\fR.
466.SS "\fBdiff-no-prefix\fR"
467.RS 0
468.IP \(bu 4
469Default: false
470.IP \(bu 4
471Type: Boolean
472.RE 0
473
474.P
475Do not show any source or destination prefix in \fBnpm diff\fR output.
476.P
477Note: this causes \fBnpm diff\fR to ignore the \fB--diff-src-prefix\fR and \fB--diff-dst-prefix\fR configs.
478.SS "\fBdiff-src-prefix\fR"
479.RS 0
480.IP \(bu 4
481Default: "a/"
482.IP \(bu 4
483Type: String
484.RE 0
485
486.P
487Source prefix to be used in \fBnpm diff\fR output.
488.SS "\fBdiff-text\fR"
489.RS 0
490.IP \(bu 4
491Default: false
492.IP \(bu 4
493Type: Boolean
494.RE 0
495
496.P
497Treat all files as text in \fBnpm diff\fR.
498.SS "\fBdiff-unified\fR"
499.RS 0
500.IP \(bu 4
501Default: 3
502.IP \(bu 4
503Type: Number
504.RE 0
505
506.P
507The number of lines of context to print in \fBnpm diff\fR.
508.SS "\fBdry-run\fR"
509.RS 0
510.IP \(bu 4
511Default: false
512.IP \(bu 4
513Type: Boolean
514.RE 0
515
516.P
517Indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, \fBinstall\fR, \fBupdate\fR, \fBdedupe\fR, \fBuninstall\fR, as well as \fBpack\fR and \fBpublish\fR.
518.P
519Note: This is NOT honored by other network related commands, eg \fBdist-tags\fR, \fBowner\fR, etc.
520.SS "\fBeditor\fR"
521.RS 0
522.IP \(bu 4
523Default: The EDITOR or VISUAL environment variables, or '%SYSTEMROOT%\[rs]notepad.exe' on Windows, or 'vi' on Unix systems
524.IP \(bu 4
525Type: String
526.RE 0
527
528.P
529The command to run for \fBnpm edit\fR and \fBnpm config edit\fR.
530.SS "\fBengine-strict\fR"
531.RS 0
532.IP \(bu 4
533Default: false
534.IP \(bu 4
535Type: Boolean
536.RE 0
537
538.P
539If set to true, then npm will stubbornly refuse to install (or even consider installing) any package that claims to not be compatible with the current Node.js version.
540.P
541This can be overridden by setting the \fB--force\fR flag.
542.SS "\fBexpect-result-count\fR"
543.RS 0
544.IP \(bu 4
545Default: null
546.IP \(bu 4
547Type: null or Number
548.RE 0
549
550.P
551Tells to expect a specific number of results from the command.
552.P
553This config cannot be used with: \fBexpect-results\fR
554.SS "\fBexpect-results\fR"
555.RS 0
556.IP \(bu 4
557Default: null
558.IP \(bu 4
559Type: null or Boolean
560.RE 0
561
562.P
563Tells npm whether or not to expect results from the command. Can be either true (expect some results) or false (expect no results).
564.P
565This config cannot be used with: \fBexpect-result-count\fR
566.SS "\fBexpires\fR"
567.RS 0
568.IP \(bu 4
569Default: null
570.IP \(bu 4
571Type: null or Number
572.RE 0
573
574.P
575When creating a Granular Access Token with \fBnpm token create\fR, this sets the expiration in days. If not specified, the server will determine the default expiration.
576.SS "\fBfetch-retries\fR"
577.RS 0
578.IP \(bu 4
579Default: 2
580.IP \(bu 4
581Type: Number
582.RE 0
583
584.P
585The "retries" config for the \fBretry\fR module to use when fetching packages from the registry.
586.P
587npm will retry idempotent read requests to the registry in the case of network failures or 5xx HTTP errors.
588.SS "\fBfetch-retry-factor\fR"
589.RS 0
590.IP \(bu 4
591Default: 10
592.IP \(bu 4
593Type: Number
594.RE 0
595
596.P
597The "factor" config for the \fBretry\fR module to use when fetching packages.
598.SS "\fBfetch-retry-maxtimeout\fR"
599.RS 0
600.IP \(bu 4
601Default: 60000 (1 minute)
602.IP \(bu 4
603Type: Number
604.RE 0
605
606.P
607The "maxTimeout" config for the \fBretry\fR module to use when fetching packages.
608.SS "\fBfetch-retry-mintimeout\fR"
609.RS 0
610.IP \(bu 4
611Default: 10000 (10 seconds)
612.IP \(bu 4
613Type: Number
614.RE 0
615
616.P
617The "minTimeout" config for the \fBretry\fR module to use when fetching packages.
618.SS "\fBfetch-timeout\fR"
619.RS 0
620.IP \(bu 4
621Default: 300000 (5 minutes)
622.IP \(bu 4
623Type: Number
624.RE 0
625
626.P
627The maximum amount of time to wait for HTTP requests to complete.
628.SS "\fBforce\fR"
629.RS 0
630.IP \(bu 4
631Default: false
632.IP \(bu 4
633Type: Boolean
634.RE 0
635
636.P
637Removes various protections against unfortunate side effects, common mistakes, unnecessary performance degradation, and malicious input.
638.RS 0
639.IP \(bu 4
640Allow clobbering non-npm files in global installs.
641.IP \(bu 4
642Allow the \fBnpm version\fR command to work on an unclean git repository.
643.IP \(bu 4
644Allow deleting the cache folder with \fBnpm cache clean\fR.
645.IP \(bu 4
646Allow installing packages that have an \fBengines\fR declaration requiring a different version of npm.
647.IP \(bu 4
648Allow installing packages that have an \fBengines\fR declaration requiring a different version of \fBnode\fR, even if \fB--engine-strict\fR is enabled.
649.IP \(bu 4
650Allow \fBnpm audit fix\fR to install modules outside your stated dependency range (including SemVer-major changes).
651.IP \(bu 4
652Allow unpublishing all versions of a published package.
653.IP \(bu 4
654Allow conflicting peerDependencies to be installed in the root project.
655.IP \(bu 4
656Implicitly set \fB--yes\fR during \fBnpm init\fR.
657.IP \(bu 4
658Allow clobbering existing values in \fBnpm pkg\fR
659.IP \(bu 4
660Allow unpublishing of entire packages (not just a single version).
661.RE 0
662
663.P
664If you don't have a clear idea of what you want to do, it is strongly recommended that you do not use this option!
665.SS "\fBforeground-scripts\fR"
666.RS 0
667.IP \(bu 4
668Default: \fBfalse\fR unless when using \fBnpm pack\fR or \fBnpm publish\fR where it defaults to \fBtrue\fR
669.IP \(bu 4
670Type: Boolean
671.RE 0
672
673.P
674Run all build scripts (ie, \fBpreinstall\fR, \fBinstall\fR, and \fBpostinstall\fR) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.
675.P
676Note that this will generally make installs run slower, and be much noisier, but can be useful for debugging.
677.SS "\fBformat-package-lock\fR"
678.RS 0
679.IP \(bu 4
680Default: true
681.IP \(bu 4
682Type: Boolean
683.RE 0
684
685.P
686Format \fBpackage-lock.json\fR or \fBnpm-shrinkwrap.json\fR as a human readable file.
687.SS "\fBfund\fR"
688.RS 0
689.IP \(bu 4
690Default: true
691.IP \(bu 4
692Type: Boolean
693.RE 0
694
695.P
696When "true" displays the message at the end of each \fBnpm install\fR acknowledging the number of dependencies looking for funding. See npm help fund for details.
697.SS "\fBgit\fR"
698.RS 0
699.IP \(bu 4
700Default: "git"
701.IP \(bu 4
702Type: String
703.RE 0
704
705.P
706The command to use for git commands. If git is installed on the computer, but is not in the \fBPATH\fR, then set this to the full path to the git binary.
707.SS "\fBgit-tag-version\fR"
708.RS 0
709.IP \(bu 4
710Default: true
711.IP \(bu 4
712Type: Boolean
713.RE 0
714
715.P
716Tag the commit when using the \fBnpm version\fR command. Setting this to false results in no commit being made at all.
717.SS "\fBglobal\fR"
718.RS 0
719.IP \(bu 4
720Default: false
721.IP \(bu 4
722Type: Boolean
723.RE 0
724
725.P
726Operates in "global" mode, so that packages are installed into the \fBprefix\fR folder instead of the current working directory. See npm help folders for more on the differences in behavior.
727.RS 0
728.IP \(bu 4
729packages are installed into the \fB{prefix}/lib/node_modules\fR folder, instead of the current working directory.
730.IP \(bu 4
731bin files are linked to \fB{prefix}/bin\fR
732.IP \(bu 4
733man pages are linked to \fB{prefix}/share/man\fR
734.RE 0
735
736.SS "\fBglobalconfig\fR"
737.RS 0
738.IP \(bu 4
739Default: The global --prefix setting plus 'etc/npmrc'. For example, '/usr/local/etc/npmrc'
740.IP \(bu 4
741Type: Path
742.RE 0
743
744.P
745The config file to read for global config options.
746.SS "\fBheading\fR"
747.RS 0
748.IP \(bu 4
749Default: "npm"
750.IP \(bu 4
751Type: String
752.RE 0
753
754.P
755The string that starts all the debugging log output.
756.SS "\fBhttps-proxy\fR"
757.RS 0
758.IP \(bu 4
759Default: null
760.IP \(bu 4
761Type: null or URL
762.RE 0
763
764.P
765A proxy to use for outgoing https requests. If the \fBHTTPS_PROXY\fR or \fBhttps_proxy\fR or \fBHTTP_PROXY\fR or \fBhttp_proxy\fR environment variables are set, proxy settings will be honored by the underlying \fBmake-fetch-happen\fR library.
766.SS "\fBif-present\fR"
767.RS 0
768.IP \(bu 4
769Default: false
770.IP \(bu 4
771Type: Boolean
772.RE 0
773
774.P
775If true, npm will not exit with an error code when \fBrun\fR is invoked for a script that isn't defined in the \fBscripts\fR section of \fBpackage.json\fR. This option can be used when it's desirable to optionally run a script when it's present and fail if the script fails. This is useful, for example, when running scripts that may only apply for some builds in an otherwise generic CI setup.
776.P
777This value is not exported to the environment for child processes.
778.SS "\fBignore-scripts\fR"
779.RS 0
780.IP \(bu 4
781Default: false
782.IP \(bu 4
783Type: Boolean
784.RE 0
785
786.P
787If true, npm does not run scripts specified in package.json files.
788.P
789Note that commands explicitly intended to run a particular script, such as \fBnpm start\fR, \fBnpm stop\fR, \fBnpm restart\fR, \fBnpm test\fR, and \fBnpm run\fR will still run their intended script if \fBignore-scripts\fR is set, but they will \fInot\fR run any pre- or post-scripts.
790.SS "\fBinclude\fR"
791.RS 0
792.IP \(bu 4
793Default:
794.IP \(bu 4
795Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
796.RE 0
797
798.P
799Option that allows for defining which types of dependencies to install.
800.P
801This is the inverse of \fB--omit=<type>\fR.
802.P
803Dependency types specified in \fB--include\fR will not be omitted, regardless of the order in which omit/include are specified on the command-line.
804.SS "\fBinclude-attestations\fR"
805.RS 0
806.IP \(bu 4
807Default: false
808.IP \(bu 4
809Type: Boolean
810.RE 0
811
812.P
813When used with \fBnpm audit signatures --json\fR, includes the full sigstore attestation bundles in the JSON output for each verified package. The bundles contain DSSE envelopes, verification material, and transparency log entries.
814.SS "\fBinclude-staged\fR"
815.RS 0
816.IP \(bu 4
817Default: false
818.IP \(bu 4
819Type: Boolean
820.RE 0
821
822.P
823Allow installing "staged" published packages, as defined by \fBnpm RFC PR #92\fR \fI\(lahttps://github.com/npm/rfcs/pull/92\(ra\fR.
824.P
825This is experimental, and not implemented by the npm public registry.
826.SS "\fBinclude-workspace-root\fR"
827.RS 0
828.IP \(bu 4
829Default: false
830.IP \(bu 4
831Type: Boolean
832.RE 0
833
834.P
835Include the workspace root when workspaces are enabled for a command.
836.P
837When false, specifying individual workspaces via the \fBworkspace\fR config, or all workspaces via the \fBworkspaces\fR flag, will cause npm to operate only on the specified workspaces, and not on the root project.
838.P
839This value is not exported to the environment for child processes.
840.SS "\fBinit-author-email\fR"
841.RS 0
842.IP \(bu 4
843Default: ""
844.IP \(bu 4
845Type: String
846.RE 0
847
848.P
849The value \fBnpm init\fR should use by default for the package author's email.
850.SS "\fBinit-author-name\fR"
851.RS 0
852.IP \(bu 4
853Default: ""
854.IP \(bu 4
855Type: String
856.RE 0
857
858.P
859The value \fBnpm init\fR should use by default for the package author's name.
860.SS "\fBinit-author-url\fR"
861.RS 0
862.IP \(bu 4
863Default: ""
864.IP \(bu 4
865Type: "" or URL
866.RE 0
867
868.P
869The value \fBnpm init\fR should use by default for the package author's homepage.
870.SS "\fBinit-license\fR"
871.RS 0
872.IP \(bu 4
873Default: "ISC"
874.IP \(bu 4
875Type: String
876.RE 0
877
878.P
879The value \fBnpm init\fR should use by default for the package license.
880.SS "\fBinit-module\fR"
881.RS 0
882.IP \(bu 4
883Default: "~/.npm-init.js"
884.IP \(bu 4
885Type: Path
886.RE 0
887
888.P
889A module that will be loaded by the \fBnpm init\fR command. See the documentation for the \fBinit-package-json\fR \fI\(lahttps://github.com/npm/init-package-json\(ra\fR module for more information, or npm help init.
890.SS "\fBinit-private\fR"
891.RS 0
892.IP \(bu 4
893Default: false
894.IP \(bu 4
895Type: Boolean
896.RE 0
897
898.P
899The value \fBnpm init\fR should use by default for the package's private flag.
900.SS "\fBinit-type\fR"
901.RS 0
902.IP \(bu 4
903Default: "commonjs"
904.IP \(bu 4
905Type: String
906.RE 0
907
908.P
909The value that \fBnpm init\fR should use by default for the package.json type field.
910.SS "\fBinit-version\fR"
911.RS 0
912.IP \(bu 4
913Default: "1.0.0"
914.IP \(bu 4
915Type: SemVer string
916.RE 0
917
918.P
919The value that \fBnpm init\fR should use by default for the package version number, if not already set in package.json.
920.SS "\fBinstall-links\fR"
921.RS 0
922.IP \(bu 4
923Default: false
924.IP \(bu 4
925Type: Boolean
926.RE 0
927
928.P
929When set file: protocol dependencies will be packed and installed as regular dependencies instead of creating a symlink. This option has no effect on workspaces.
930.SS "\fBinstall-strategy\fR"
931.RS 0
932.IP \(bu 4
933Default: "hoisted"
934.IP \(bu 4
935Type: "hoisted", "nested", "shallow", or "linked"
936.RE 0
937
938.P
939Sets the strategy for installing packages in node_modules. hoisted (default): Install non-duplicated in top-level, and duplicated as necessary within directory structure. nested: (formerly --legacy-bundling) install in place, no hoisting. shallow (formerly --global-style) only install direct deps at top-level. linked: (experimental) install in node_modules/.store, link in place, unhoisted.
940.SS "\fBjson\fR"
941.RS 0
942.IP \(bu 4
943Default: false
944.IP \(bu 4
945Type: Boolean
946.RE 0
947
948.P
949Whether or not to output JSON data, rather than the normal output.
950.RS 0
951.IP \(bu 4
952In \fBnpm pkg set\fR it enables parsing set values with JSON.parse() before saving them to your \fBpackage.json\fR.
953.RE 0
954
955.P
956Not supported by all npm commands.
957.SS "\fBlegacy-peer-deps\fR"
958.RS 0
959.IP \(bu 4
960Default: false
961.IP \(bu 4
962Type: Boolean
963.RE 0
964
965.P
966Causes npm to completely ignore \fBpeerDependencies\fR when building a package tree, as in npm versions 3 through 6.
967.P
968If a package cannot be installed because of overly strict \fBpeerDependencies\fR that collide, it provides a way to move forward resolving the situation.
969.P
970This differs from \fB--omit=peer\fR, in that \fB--omit=peer\fR will avoid unpacking \fBpeerDependencies\fR on disk, but will still design a tree such that \fBpeerDependencies\fR \fIcould\fR be unpacked in a correct place.
971.P
972Use of \fBlegacy-peer-deps\fR is not recommended, as it will not enforce the \fBpeerDependencies\fR contract that meta-dependencies may rely on.
973.SS "\fBlibc\fR"
974.RS 0
975.IP \(bu 4
976Default: null
977.IP \(bu 4
978Type: null or String
979.RE 0
980
981.P
982Override libc of native modules to install. Acceptable values are same as \fBlibc\fR field of package.json
983.SS "\fBlink\fR"
984.RS 0
985.IP \(bu 4
986Default: false
987.IP \(bu 4
988Type: Boolean
989.RE 0
990
991.P
992Used with \fBnpm ls\fR, limiting output to only those packages that are linked.
993.SS "\fBlocal-address\fR"
994.RS 0
995.IP \(bu 4
996Default: null
997.IP \(bu 4
998Type: IP Address
999.RE 0
1000
1001.P
1002The IP address of the local interface to use when making connections to the npm registry. Must be IPv4 in versions of Node prior to 0.12.
1003.SS "\fBlocation\fR"
1004.RS 0
1005.IP \(bu 4
1006Default: "user" unless \fB--global\fR is passed, which will also set this value to "global"
1007.IP \(bu 4
1008Type: "global", "user", or "project"
1009.RE 0
1010
1011.P
1012When passed to \fBnpm config\fR this refers to which config file to use.
1013.P
1014When set to "global" mode, packages are installed into the \fBprefix\fR folder instead of the current working directory. See npm help folders for more on the differences in behavior.
1015.RS 0
1016.IP \(bu 4
1017packages are installed into the \fB{prefix}/lib/node_modules\fR folder, instead of the current working directory.
1018.IP \(bu 4
1019bin files are linked to \fB{prefix}/bin\fR
1020.IP \(bu 4
1021man pages are linked to \fB{prefix}/share/man\fR
1022.RE 0
1023
1024.SS "\fBlockfile-version\fR"
1025.RS 0
1026.IP \(bu 4
1027Default: Version 3 if no lockfile, auto-converting v1 lockfiles to v3; otherwise, maintain current lockfile version.
1028.IP \(bu 4
1029Type: null, 1, 2, 3, "1", "2", or "3"
1030.RE 0
1031
1032.P
1033Set the lockfile format version to be used in package-lock.json and npm-shrinkwrap-json files. Possible options are:
1034.P
10351: The lockfile version used by npm versions 5 and 6. Lacks some data that is used during the install, resulting in slower and possibly less deterministic installs. Prevents lockfile churn when interoperating with older npm versions.
1036.P
10372: The default lockfile version used by npm version 7 and 8. Includes both the version 1 lockfile data and version 3 lockfile data, for maximum determinism and interoperability, at the expense of more bytes on disk.
1038.P
10393: Only the new lockfile information introduced in npm version 7. Smaller on disk than lockfile version 2, but not interoperable with older npm versions. Ideal if all users are on npm version 7 and higher.
1040.SS "\fBloglevel\fR"
1041.RS 0
1042.IP \(bu 4
1043Default: "notice"
1044.IP \(bu 4
1045Type: "silent", "error", "warn", "notice", "http", "info", "verbose", or "silly"
1046.RE 0
1047
1048.P
1049What level of logs to report. All logs are written to a debug log, with the path to that file printed if the execution of a command fails.
1050.P
1051Any logs of a higher level than the setting are shown. The default is "notice".
1052.P
1053See also the \fBforeground-scripts\fR config.
1054.SS "\fBlogs-dir\fR"
1055.RS 0
1056.IP \(bu 4
1057Default: A directory named \fB_logs\fR inside the cache
1058.IP \(bu 4
1059Type: null or Path
1060.RE 0
1061
1062.P
1063The location of npm's log directory. See npm help logging for more information.
1064.SS "\fBlogs-max\fR"
1065.RS 0
1066.IP \(bu 4
1067Default: 10
1068.IP \(bu 4
1069Type: Number
1070.RE 0
1071
1072.P
1073The maximum number of log files to store.
1074.P
1075If set to 0, no log files will be written for the current run.
1076.SS "\fBlong\fR"
1077.RS 0
1078.IP \(bu 4
1079Default: false
1080.IP \(bu 4
1081Type: Boolean
1082.RE 0
1083
1084.P
1085Show extended information in \fBls\fR, \fBsearch\fR, and \fBhelp-search\fR.
1086.SS "\fBmaxsockets\fR"
1087.RS 0
1088.IP \(bu 4
1089Default: 15
1090.IP \(bu 4
1091Type: Number
1092.RE 0
1093
1094.P
1095The maximum number of connections to use per origin (protocol/host/port combination).
1096.SS "\fBmessage\fR"
1097.RS 0
1098.IP \(bu 4
1099Default: "%s"
1100.IP \(bu 4
1101Type: String
1102.RE 0
1103
1104.P
1105Commit message which is used by \fBnpm version\fR when creating version commit.
1106.P
1107Any "%s" in the message will be replaced with the version number.
1108.SS "\fBmin-release-age\fR"
1109.RS 0
1110.IP \(bu 4
1111Default: null
1112.IP \(bu 4
1113Type: null or Number
1114.RE 0
1115
1116.P
1117If set, npm will build the npm tree such that only versions that were available more than the given number of days ago will be installed. If there are no versions available for the current set of dependencies, the command will error.
1118.P
1119This flag is a complement to \fBbefore\fR, which accepts an exact date instead of a relative number of days.
1120.P
1121This config cannot be used with: \fBbefore\fR
1122.P
1123This value is not exported to the environment for child processes.
1124.SS "\fBname\fR"
1125.RS 0
1126.IP \(bu 4
1127Default: null
1128.IP \(bu 4
1129Type: null or String
1130.RE 0
1131
1132.P
1133When creating a Granular Access Token with \fBnpm token create\fR, this sets the name/description for the token.
1134.SS "\fBnode-gyp\fR"
1135.RS 0
1136.IP \(bu 4
1137Default: The path to the node-gyp bin that ships with npm
1138.IP \(bu 4
1139Type: Path
1140.RE 0
1141
1142.P
1143This is the location of the "node-gyp" bin. By default it uses one that ships with npm itself.
1144.P
1145You can use this config to specify your own "node-gyp" to run when it is required to build a package.
1146.SS "\fBnode-options\fR"
1147.RS 0
1148.IP \(bu 4
1149Default: null
1150.IP \(bu 4
1151Type: null or String
1152.RE 0
1153
1154.P
1155Options to pass through to Node.js via the \fBNODE_OPTIONS\fR environment variable. This does not impact how npm itself is executed but it does impact how lifecycle scripts are called.
1156.SS "\fBnoproxy\fR"
1157.RS 0
1158.IP \(bu 4
1159Default: The value of the NO_PROXY environment variable
1160.IP \(bu 4
1161Type: String (can be set multiple times)
1162.RE 0
1163
1164.P
1165Domain extensions that should bypass any proxies.
1166.P
1167Also accepts a comma-delimited string.
1168.SS "\fBoffline\fR"
1169.RS 0
1170.IP \(bu 4
1171Default: false
1172.IP \(bu 4
1173Type: Boolean
1174.RE 0
1175
1176.P
1177Force offline mode: no network requests will be done during install. To allow the CLI to fill in missing cache data, see \fB--prefer-offline\fR.
1178.SS "\fBomit\fR"
1179.RS 0
1180.IP \(bu 4
1181Default: 'dev' if the \fBNODE_ENV\fR environment variable is set to 'production'; otherwise, empty.
1182.IP \(bu 4
1183Type: "dev", "optional", or "peer" (can be set multiple times)
1184.RE 0
1185
1186.P
1187Dependency types to omit from the installation tree on disk.
1188.P
1189Note that these dependencies \fIare\fR still resolved and added to the \fBpackage-lock.json\fR or \fBnpm-shrinkwrap.json\fR file. They are just not physically installed on disk.
1190.P
1191If a package type appears in both the \fB--include\fR and \fB--omit\fR lists, then it will be included.
1192.P
1193If the resulting omit list includes \fB'dev'\fR, then the \fBNODE_ENV\fR environment variable will be set to \fB'production'\fR for all lifecycle scripts.
1194.SS "\fBomit-lockfile-registry-resolved\fR"
1195.RS 0
1196.IP \(bu 4
1197Default: false
1198.IP \(bu 4
1199Type: Boolean
1200.RE 0