deps/npm/doc/misc/npm-config.md

   1 npm-config(7) -- More than you probably want to know about npm configuration
   2 ============================================================================
   3
   4 ## DESCRIPTION
   5
   6 npm gets its configuration values from 6 sources, in this priority:
   7
   8 ### Command Line Flags
   9
  10 Putting `--foo bar` on the command line sets the `foo` configuration
  11 parameter to `"bar"`.  A `--` argument tells the cli parser to stop
  12 reading flags.  A `--flag` parameter that is at the *end* of the
  13 command will be given the value of `true`.
  14
  15 ### Environment Variables
  16
  17 Any environment variables that start with `npm_config_` will be
  18 interpreted as a configuration parameter.  For example, putting
  19 `npm_config_foo=bar` in your environment will set the `foo`
  20 configuration parameter to `bar`.  Any environment configurations that
  21 are not given a value will be given the value of `true`.  Config
  22 values are case-insensitive, so `NPM_CONFIG_FOO=bar` will work the
  23 same.
  24
  25 ### npmrc Files
  26
  27 The three relevant files are:
  28
  29 * per-user config file (~/.npmrc)
  30 * global config file ($PREFIX/npmrc)
  31 * npm builtin config file (/path/to/npm/npmrc)
  32
  33 See npmrc(5) for more details.
  34
  35 ### Default Configs
  36
  37 A set of configuration parameters that are internal to npm, and are
  38 defaults if nothing else is specified.
  39
  40 ## Shorthands and Other CLI Niceties
  41
  42 The following shorthands are parsed on the command-line:
  43
  44 * `-v`: `--version`
  45 * `-h`, `-?`, `--help`, `-H`: `--usage`
  46 * `-s`, `--silent`: `--loglevel silent`
  47 * `-q`, `--quiet`: `--loglevel warn`
  48 * `-d`: `--loglevel info`
  49 * `-dd`, `--verbose`: `--loglevel verbose`
  50 * `-ddd`: `--loglevel silly`
  51 * `-g`: `--global`
  52 * `-l`: `--long`
  53 * `-m`: `--message`
  54 * `-p`, `--porcelain`: `--parseable`
  55 * `-reg`: `--registry`
  56 * `-v`: `--version`
  57 * `-f`: `--force`
  58 * `-desc`: `--description`
  59 * `-S`: `--save`
  60 * `-D`: `--save-dev`
  61 * `-O`: `--save-optional`
  62 * `-B`: `--save-bundle`
  63 * `-y`: `--yes`
  64 * `-n`: `--yes false`
  65 * `ll` and `la` commands: `ls --long`
  66
  67 If the specified configuration param resolves unambiguously to a known
  68 configuration parameter, then it is expanded to that configuration
  69 parameter.  For example:
  70
  71     npm ls --par
  72     # same as:
  73     npm ls --parseable
  74
  75 If multiple single-character shorthands are strung together, and the
  76 resulting combination is unambiguously not some other configuration
  77 param, then it is expanded to its various component pieces.  For
  78 example:
  79
  80     npm ls -gpld
  81     # same as:
  82     npm ls --global --parseable --long --loglevel info
  83
  84 ## Per-Package Config Settings
  85
  86 When running scripts (see `npm-scripts(7)`) the package.json "config"
  87 keys are overwritten in the environment if there is a config param of
  88 `<name>[@<version>]:<key>`.  For example, if the package.json has
  89 this:
  90
  91     { "name" : "foo"
  92     , "config" : { "port" : "8080" }
  93     , "scripts" : { "start" : "node server.js" } }
  94
  95 and the server.js is this:
  96
  97     http.createServer(...).listen(process.env.npm_package_config_port)
  98
  99 then the user could change the behavior by doing:
 100
 101     npm config set foo:port 80
 102
 103 See package.json(5) for more information.
 104
 105 ## Config Settings
 106
 107 ### always-auth
 108
 109 * Default: false
 110 * Type: Boolean
 111
 112 Force npm to always require authentication when accessing the registry,
 113 even for `GET` requests.
 114
 115 ### bin-links
 116
 117 * Default: `true`
 118 * Type: Boolean
 119
 120 Tells npm to create symlinks (or `.cmd` shims on Windows) for package
 121 executables.
 122
 123 Set to false to have it not do this.  This can be used to work around
 124 the fact that some file systems don't support symlinks, even on
 125 ostensibly Unix systems.
 126
 127 ### browser
 128
 129 * Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"`
 130 * Type: String
 131
 132 The browser that is called by the `npm docs` command to open websites.
 133
 134 ### ca
 135
 136 * Default: The npm CA certificate
 137 * Type: String or null
 138
 139 The Certificate Authority signing certificate that is trusted for SSL
 140 connections to the registry.
 141
 142 Set to `null` to only allow "known" registrars, or to a specific CA cert
 143 to trust only that specific signing authority.
 144
 145 See also the `strict-ssl` config.
 146
 147 ### cache
 148
 149 * Default: Windows: `%AppData%\npm-cache`, Posix: `~/.npm`
 150 * Type: path
 151
 152 The location of npm's cache directory.  See `npm-cache(1)`
 153
 154 ### cache-lock-stale
 155
 156 * Default: 60000 (1 minute)
 157 * Type: Number
 158
 159 The number of ms before cache folder lockfiles are considered stale.
 160
 161 ### cache-lock-retries
 162
 163 * Default: 10
 164 * Type: Number
 165
 166 Number of times to retry to acquire a lock on cache folder lockfiles.
 167
 168 ### cache-lock-wait
 169
 170 * Default: 10000 (10 seconds)
 171 * Type: Number
 172
 173 Number of ms to wait for cache lock files to expire.
 174
 175 ### cache-max
 176
 177 * Default: Infinity
 178 * Type: Number
 179
 180 The maximum time (in seconds) to keep items in the registry cache before
 181 re-checking against the registry.
 182
 183 Note that no purging is done unless the `npm cache clean` command is
 184 explicitly used, and that only GET requests use the cache.
 185
 186 ### cache-min
 187
 188 * Default: 10
 189 * Type: Number
 190
 191 The minimum time (in seconds) to keep items in the registry cache before
 192 re-checking against the registry.
 193
 194 Note that no purging is done unless the `npm cache clean` command is
 195 explicitly used, and that only GET requests use the cache.
 196
 197 ### cert
 198
 199 * Default: `null`
 200 * Type: String
 201
 202 A client certificate to pass when accessing the registry.
 203
 204 ### color
 205
 206 * Default: true on Posix, false on Windows
 207 * Type: Boolean or `"always"`
 208
 209 If false, never shows colors.  If `"always"` then always shows colors.
 210 If true, then only prints color codes for tty file descriptors.
 211
 212 ### depth
 213
 214 * Default: Infinity
 215 * Type: Number
 216
 217 The depth to go when recursing directories for `npm ls` and
 218 `npm cache ls`.
 219
 220 ### description
 221
 222 * Default: true
 223 * Type: Boolean
 224
 225 Show the description in `npm search`
 226
 227 ### dev
 228
 229 * Default: false
 230 * Type: Boolean
 231
 232 Install `dev-dependencies` along with packages.
 233
 234 Note that `dev-dependencies` are also installed if the `npat` flag is
 235 set.
 236
 237 ### editor
 238
 239 * Default: `EDITOR` environment variable if set, or `"vi"` on Posix,
 240   or `"notepad"` on Windows.
 241 * Type: path
 242
 243 The command to run for `npm edit` or `npm config edit`.
 244
 245 ### email
 246
 247 The email of the logged-in user.
 248
 249 Set by the `npm adduser` command.  Should not be set explicitly.
 250
 251 ### engine-strict
 252
 253 * Default: false
 254 * Type: Boolean
 255
 256 If set to true, then npm will stubbornly refuse to install (or even
 257 consider installing) any package that claims to not be compatible with
 258 the current Node.js version.
 259
 260 ### force
 261
 262 * Default: false
 263 * Type: Boolean
 264
 265 Makes various commands more forceful.
 266
 267 * lifecycle script failure does not block progress.
 268 * publishing clobbers previously published versions.
 269 * skips cache when requesting from the registry.
 270 * prevents checks against clobbering non-npm files.
 271
 272 ### fetch-retries
 273
 274 * Default: 2
 275 * Type: Number
 276
 277 The "retries" config for the `retry` module to use when fetching
 278 packages from the registry.
 279
 280 ### fetch-retry-factor
 281
 282 * Default: 10
 283 * Type: Number
 284
 285 The "factor" config for the `retry` module to use when fetching
 286 packages.
 287
 288 ### fetch-retry-mintimeout
 289
 290 * Default: 10000 (10 seconds)
 291 * Type: Number
 292
 293 The "minTimeout" config for the `retry` module to use when fetching
 294 packages.
 295
 296 ### fetch-retry-maxtimeout
 297
 298 * Default: 60000 (1 minute)
 299 * Type: Number
 300
 301 The "maxTimeout" config for the `retry` module to use when fetching
 302 packages.
 303
 304 ### git
 305
 306 * Default: `"git"`
 307 * Type: String
 308
 309 The command to use for git commands.  If git is installed on the
 310 computer, but is not in the `PATH`, then set this to the full path to
 311 the git binary.
 312
 313 ### git-tag-version
 314
 315 * Default: `true`
 316 * Type: Boolean
 317
 318 Tag the commit when using the `npm version` command.
 319
 320 ### global
 321
 322 * Default: false
 323 * Type: Boolean
 324
 325 Operates in "global" mode, so that packages are installed into the
 326 `prefix` folder instead of the current working directory.  See
 327 `npm-folders(5)` for more on the differences in behavior.
 328
 329 * packages are installed into the `{prefix}/lib/node_modules` folder, instead of the
 330   current working directory.
 331 * bin files are linked to `{prefix}/bin`
 332 * man pages are linked to `{prefix}/share/man`
 333
 334 ### globalconfig
 335
 336 * Default: {prefix}/etc/npmrc
 337 * Type: path
 338
 339 The config file to read for global config options.
 340
 341 ### group
 342
 343 * Default: GID of the current process
 344 * Type: String or Number
 345
 346 The group to use when running package scripts in global mode as the root
 347 user.
 348
 349 ### heading
 350
 351 * Default: `"npm"`
 352 * Type: String
 353
 354 The string that starts all the debugging log output.
 355
 356 ### https-proxy
 357
 358 * Default: the `HTTPS_PROXY` or `https_proxy` or `HTTP_PROXY` or
 359   `http_proxy` environment variables.
 360 * Type: url
 361
 362 A proxy to use for outgoing https requests.
 363
 364 ### ignore-scripts
 365
 366 * Default: false
 367 * Type: Boolean
 368
 369 If true, npm does not run scripts specified in package.json files.
 370
 371 ### init-module
 372
 373 * Default: ~/.npm-init.js
 374 * Type: path
 375
 376 A module that will be loaded by the `npm init` command.  See the
 377 documentation for the
 378 [init-package-json](https://github.com/isaacs/init-package-json) module
 379 for more information, or npm-init(1).
 380
 381 ### init.author.name
 382
 383 * Default: ""
 384 * Type: String
 385
 386 The value `npm init` should use by default for the package author's name.
 387
 388 ### init.author.email
 389
 390 * Default: ""
 391 * Type: String
 392
 393 The value `npm init` should use by default for the package author's email.
 394
 395 ### init.author.url
 396
 397 * Default: ""
 398 * Type: String
 399
 400 The value `npm init` should use by default for the package author's homepage.
 401
 402 ### init.license
 403
 404 * Default: "BSD-2-Clause"
 405 * Type: String
 406
 407 The value `npm init` should use by default for the package license.
 408
 409 ### json
 410
 411 * Default: false
 412 * Type: Boolean
 413
 414 Whether or not to output JSON data, rather than the normal output.
 415
 416 This feature is currently experimental, and the output data structures
 417 for many commands is either not implemented in JSON yet, or subject to
 418 change.  Only the output from `npm ls --json` is currently valid.
 419
 420 ### key
 421
 422 * Default: `null`
 423 * Type: String
 424
 425 A client key to pass when accessing the registry.
 426
 427 ### link
 428
 429 * Default: false
 430 * Type: Boolean
 431
 432 If true, then local installs will link if there is a suitable globally
 433 installed package.
 434
 435 Note that this means that local installs can cause things to be
 436 installed into the global space at the same time.  The link is only done
 437 if one of the two conditions are met:
 438
 439 * The package is not already installed globally, or
 440 * the globally installed version is identical to the version that is
 441   being installed locally.
 442
 443 ### local-address
 444
 445 * Default: undefined
 446 * Type: IP Address
 447
 448 The IP address of the local interface to use when making connections
 449 to the npm registry.  Must be IPv4 in versions of Node prior to 0.12.
 450
 451 ### loglevel
 452
 453 * Default: "http"
 454 * Type: String
 455 * Values: "silent", "win", "error", "warn", "http", "info", "verbose", "silly"
 456
 457 What level of logs to report.  On failure, *all* logs are written to
 458 `npm-debug.log` in the current working directory.
 459
 460 Any logs of a higher level than the setting are shown.
 461 The default is "http", which shows http, warn, and error output.
 462
 463 ### logstream
 464
 465 * Default: process.stderr
 466 * Type: Stream
 467
 468 This is the stream that is passed to the
 469 [npmlog](https://github.com/isaacs/npmlog) module at run time.
 470
 471 It cannot be set from the command line, but if you are using npm
 472 programmatically, you may wish to send logs to somewhere other than
 473 stderr.
 474
 475 If the `color` config is set to true, then this stream will receive
 476 colored output if it is a TTY.
 477
 478 ### long
 479
 480 * Default: false
 481 * Type: Boolean
 482
 483 Show extended information in `npm ls`
 484
 485 ### message
 486
 487 * Default: "%s"
 488 * Type: String
 489
 490 Commit message which is used by `npm version` when creating version commit.
 491
 492 Any "%s" in the message will be replaced with the version number.
 493
 494 ### node-version
 495
 496 * Default: process.version
 497 * Type: semver or false
 498
 499 The node version to use when checking package's "engines" hash.
 500
 501 ### npat
 502
 503 * Default: false
 504 * Type: Boolean
 505
 506 Run tests on installation.
 507
 508 ### onload-script
 509
 510 * Default: false
 511 * Type: path
 512
 513 A node module to `require()` when npm loads.  Useful for programmatic
 514 usage.
 515
 516 ### optional
 517
 518 * Default: true
 519 * Type: Boolean
 520
 521 Attempt to install packages in the `optionalDependencies` hash.  Note
 522 that if these packages fail to install, the overall installation
 523 process is not aborted.
 524
 525 ### parseable
 526
 527 * Default: false
 528 * Type: Boolean
 529
 530 Output parseable results from commands that write to
 531 standard output.
 532
 533 ### prefix
 534
 535 * Default: see npm-folders(5)
 536 * Type: path
 537
 538 The location to install global items.  If set on the command line, then
 539 it forces non-global commands to run in the specified folder.
 540
 541 ### production
 542
 543 * Default: false
 544 * Type: Boolean
 545
 546 Set to true to run in "production" mode.
 547
 548 1. devDependencies are not installed at the topmost level when running
 549    local `npm install` without any arguments.
 550 2. Set the NODE_ENV="production" for lifecycle scripts.
 551
 552 ### proprietary-attribs
 553
 554 * Default: true
 555 * Type: Boolean
 556
 557 Whether or not to include proprietary extended attributes in the
 558 tarballs created by npm.
 559
 560 Unless you are expecting to unpack package tarballs with something other
 561 than npm -- particularly a very outdated tar implementation -- leave
 562 this as true.
 563
 564 ### proxy
 565
 566 * Default: `HTTP_PROXY` or `http_proxy` environment variable, or null
 567 * Type: url
 568
 569 A proxy to use for outgoing http requests.
 570
 571 ### rebuild-bundle
 572
 573 * Default: true
 574 * Type: Boolean
 575
 576 Rebuild bundled dependencies after installation.
 577
 578 ### registry
 579
 580 * Default: https://registry.npmjs.org/
 581 * Type: url
 582
 583 The base URL of the npm package registry.
 584
 585 ### rollback
 586
 587 * Default: true
 588 * Type: Boolean
 589
 590 Remove failed installs.
 591
 592 ### save
 593
 594 * Default: false
 595 * Type: Boolean
 596
 597 Save installed packages to a package.json file as dependencies.
 598
 599 When used with the `npm rm` command, it removes it from the dependencies
 600 hash.
 601
 602 Only works if there is already a package.json file present.
 603
 604 ### save-bundle
 605
 606 * Default: false
 607 * Type: Boolean
 608
 609 If a package would be saved at install time by the use of `--save`,
 610 `--save-dev`, or `--save-optional`, then also put it in the
 611 `bundleDependencies` list.
 612
 613 When used with the `npm rm` command, it removes it from the
 614 bundledDependencies list.
 615
 616 ### save-dev
 617
 618 * Default: false
 619 * Type: Boolean
 620
 621 Save installed packages to a package.json file as devDependencies.
 622
 623 When used with the `npm rm` command, it removes it from the devDependencies
 624 hash.
 625
 626 Only works if there is already a package.json file present.
 627
 628 ### save-optional
 629
 630 * Default: false
 631 * Type: Boolean
 632
 633 Save installed packages to a package.json file as optionalDependencies.
 634
 635 When used with the `npm rm` command, it removes it from the devDependencies
 636 hash.
 637
 638 Only works if there is already a package.json file present.
 639
 640 ### searchopts
 641
 642 * Default: ""
 643 * Type: String
 644
 645 Space-separated options that are always passed to search.
 646
 647 ### searchexclude
 648
 649 * Default: ""
 650 * Type: String
 651
 652 Space-separated options that limit the results from search.
 653
 654 ### searchsort
 655
 656 * Default: "name"
 657 * Type: String
 658 * Values: "name", "-name", "date", "-date", "description",
 659   "-description", "keywords", "-keywords"
 660
 661 Indication of which field to sort search results by.  Prefix with a `-`
 662 character to indicate reverse sort.
 663
 664 ### shell
 665
 666 * Default: SHELL environment variable, or "bash" on Posix, or "cmd" on
 667   Windows
 668 * Type: path
 669
 670 The shell to run for the `npm explore` command.
 671
 672 ### shrinkwrap
 673
 674 * Default: true
 675 * Type: Boolean
 676
 677 If set to false, then ignore `npm-shrinkwrap.json` files when
 678 installing.
 679
 680 ### sign-git-tag
 681
 682 * Default: false
 683 * Type: Boolean
 684
 685 If set to true, then the `npm version` command will tag the version
 686 using `-s` to add a signature.
 687
 688 Note that git requires you to have set up GPG keys in your git configs
 689 for this to work properly.
 690
 691 ### strict-ssl
 692
 693 * Default: true
 694 * Type: Boolean
 695
 696 Whether or not to do SSL key validation when making requests to the
 697 registry via https.
 698
 699 See also the `ca` config.
 700
 701 ### tag
 702
 703 * Default: latest
 704 * Type: String
 705
 706 If you ask npm to install a package and don't tell it a specific version, then
 707 it will install the specified tag.
 708
 709 Also the tag that is added to the package@version specified by the `npm
 710 tag` command, if no explicit tag is given.
 711
 712 ### tmp
 713
 714 * Default: TMPDIR environment variable, or "/tmp"
 715 * Type: path
 716
 717 Where to store temporary files and folders.  All temp files are deleted
 718 on success, but left behind on failure for forensic purposes.
 719
 720 ### unicode
 721
 722 * Default: true
 723 * Type: Boolean
 724
 725 When set to true, npm uses unicode characters in the tree output.  When
 726 false, it uses ascii characters to draw trees.
 727
 728 ### unsafe-perm
 729
 730 * Default: false if running as root, true otherwise
 731 * Type: Boolean
 732
 733 Set to true to suppress the UID/GID switching when running package
 734 scripts.  If set explicitly to false, then installing as a non-root user
 735 will fail.
 736
 737 ### usage
 738
 739 * Default: false
 740 * Type: Boolean
 741
 742 Set to show short usage output (like the -H output)
 743 instead of complete help when doing `npm-help(1)`.
 744
 745 ### user
 746
 747 * Default: "nobody"
 748 * Type: String or Number
 749
 750 The UID to set to when running package scripts as root.
 751
 752 ### username
 753
 754 * Default: null
 755 * Type: String
 756
 757 The username on the npm registry.  Set with `npm adduser`
 758
 759 ### userconfig
 760
 761 * Default: ~/.npmrc
 762 * Type: path
 763
 764 The location of user-level configuration settings.
 765
 766 ### umask
 767
 768 * Default: 022
 769 * Type: Octal numeric string
 770
 771 The "umask" value to use when setting the file creation mode on files
 772 and folders.
 773
 774 Folders and executables are given a mode which is `0777` masked against
 775 this value.  Other files are given a mode which is `0666` masked against
 776 this value.  Thus, the defaults are `0755` and `0644` respectively.
 777
 778 ### user-agent
 779
 780 * Default: node/{process.version} {process.platform} {process.arch}
 781 * Type: String
 782
 783 Sets a User-Agent to the request header
 784
 785 ### version
 786
 787 * Default: false
 788 * Type: boolean
 789
 790 If true, output the npm version and exit successfully.
 791
 792 Only relevant when specified explicitly on the command line.
 793
 794 ### versions
 795
 796 * Default: false
 797 * Type: boolean
 798
 799 If true, output the npm version as well as node's `process.versions`
 800 hash, and exit successfully.
 801
 802 Only relevant when specified explicitly on the command line.
 803
 804 ### viewer
 805
 806 * Default: "man" on Posix, "browser" on Windows
 807 * Type: path
 808
 809 The program to use to view help content.
 810
 811 Set to `"browser"` to view html help content in the default web browser.
 812
 813 ## SEE ALSO
 814
 815 * npm-config(1)
 816 * npm-config(7)
 817 * npmrc(5)
 818 * npm-scripts(7)
 819 * npm-folders(5)
 820 * npm(1)