org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/man/man1/npm-install.1

   1 .TH "NPM\-INSTALL" "1" "October 2016" "" ""
   2 .SH "NAME"
   3 \fBnpm-install\fR \- Install a package
   4 .SH SYNOPSIS
   5 .P
   6 .RS 2
   7 .nf
   8 npm install (with no args in a package dir)
   9 npm install <tarball file>
  10 npm install <tarball url>
  11 npm install <folder>
  12 npm install [@<scope>/]<name> [\-\-save|\-\-save\-dev|\-\-save\-optional] [\-\-save\-exact] [\-\-save\-bundle]
  13 npm install [@<scope>/]<name>@<tag>
  14 npm install [@<scope>/]<name>@<version>
  15 npm install [@<scope>/]<name>@<version range>
  16 npm i (with any of the previous argument usage)
  17 .fi
  18 .RE
  19 .SH DESCRIPTION
  20 .P
  21 This command installs a package, and any packages that it depends on\. If the
  22 package has a shrinkwrap file, the installation of dependencies will be driven
  23 by that\. See npm help shrinkwrap\.
  24 .P
  25 A \fBpackage\fP is:
  26 .RS 0
  27 .IP \(bu 2
  28 a) a folder containing a program described by a npm help 5 \fBpackage\.json\fP file
  29 .IP \(bu 2
  30 b) a gzipped tarball containing (a)
  31 .IP \(bu 2
  32 c) a url that resolves to (b)
  33 .IP \(bu 2
  34 d) a \fB<name>@<version>\fP that is published on the registry (see npm help 7 \fBnpm\-registry\fP) with (c)
  35 .IP \(bu 2
  36 e) a \fB<name>@<tag>\fP (see npm help \fBnpm\-dist\-tag\fP) that points to (d)
  37 .IP \(bu 2
  38 f) a \fB<name>\fP that has a "latest" tag satisfying (e)
  39 .IP \(bu 2
  40 g) a \fB<git remote url>\fP that resolves to (b)
  41
  42 .RE
  43 .P
  44 Even if you never publish your package, you can still get a lot of
  45 benefits of using npm if you just want to write a node program (a), and
  46 perhaps if you also want to be able to easily install it elsewhere
  47 after packing it up into a tarball (b)\.
  48 .RS 0
  49 .IP \(bu 2
  50 \fBnpm install\fP (in package directory, no arguments):
  51   Install the dependencies in the local node_modules folder\.
  52   In global mode (ie, with \fB\-g\fP or \fB\-\-global\fP appended to the command),
  53   it installs the current package context (ie, the current working
  54   directory) as a global package\.
  55   By default, \fBnpm install\fP will install all modules listed as dependencies
  56   in npm help 5 \fBpackage\.json\fP\|\.
  57   With the \fB\-\-production\fP flag (or when the \fBNODE_ENV\fP environment variable
  58   is set to \fBproduction\fP), npm will not install modules listed in
  59   \fBdevDependencies\fP\|\.
  60 .IP \(bu 2
  61 \fBnpm install <folder>\fP:
  62   Install a package that is sitting in a folder on the filesystem\.
  63 .IP \(bu 2
  64 \fBnpm install <tarball file>\fP:
  65   Install a package that is sitting on the filesystem\.  Note: if you just want
  66   to link a dev directory into your npm root, you can do this more easily by
  67   using \fBnpm link\fP\|\.
  68   Example:
  69 .P
  70 .RS 2
  71 .nf
  72     npm install \./package\.tgz
  73 .fi
  74 .RE
  75 .IP \(bu 2
  76 \fBnpm install <tarball url>\fP:
  77   Fetch the tarball url, and then install it\.  In order to distinguish between
  78   this and other options, the argument must start with "http://" or "https://"
  79   Example:
  80 .P
  81 .RS 2
  82 .nf
  83     npm install https://github\.com/indexzero/forever/tarball/v0\.5\.6
  84 .fi
  85 .RE
  86 .IP \(bu 2
  87 \fBnpm install [@<scope>/]<name> [\-\-save|\-\-save\-dev|\-\-save\-optional]\fP:
  88   Do a \fB<name>@<tag>\fP install, where \fB<tag>\fP is the "tag" config\. (See
  89   npm help 7 \fBnpm\-config\fP\|\. The config's default value is \fBlatest\fP\|\.)
  90   In most cases, this will install the latest version
  91   of the module published on npm\.
  92   Example:
  93 .P
  94 .RS 2
  95 .nf
  96     npm install sax
  97 .fi
  98 .RE
  99   \fBnpm install\fP takes 3 exclusive, optional flags which save or update
 100   the package version in your main package\.json:
 101 .RS 0
 102 .IP \(bu 2
 103 \fB\-\-save\fP: Package will appear in your \fBdependencies\fP\|\.
 104 .IP \(bu 2
 105 \fB\-\-save\-dev\fP: Package will appear in your \fBdevDependencies\fP\|\.
 106 .IP \(bu 2
 107 \fB\-\-save\-optional\fP: Package will appear in your \fBoptionalDependencies\fP\|\.
 108 When using any of the above options to save dependencies to your
 109 package\.json, there are two additional, optional flags:
 110 .IP \(bu 2
 111 \fB\-\-save\-exact\fP: Saved dependencies will be configured with an
 112 exact version rather than using npm's default semver range
 113 operator\.
 114 .IP \(bu 2
 115 \fB\-B, \-\-save\-bundle\fP: Saved dependencies will also be added to your \fBbundleDependencies\fP list\.
 116 Note: if you do not include the @\-symbol on your scope name, npm will
 117 interpret this as a GitHub repository instead, see below\. Scopes names
 118 must also be followed by a slash\.
 119 Examples:
 120 .P
 121 .RS 2
 122 .nf
 123 npm install sax \-\-save
 124 npm install githubname/reponame
 125 npm install @myorg/privatepackage
 126 npm install node\-tap \-\-save\-dev
 127 npm install dtrace\-provider \-\-save\-optional
 128 npm install readable\-stream \-\-save \-\-save\-exact
 129 npm install ansi\-regex \-\-save \-\-save\-bundle
 130 .fi
 131 .RE
 132
 133 .RE
 134
 135 .RE
 136 .P
 137 .RS 2
 138 .nf
 139 **Note**: If there is a file or folder named `<name>` in the current
 140 working directory, then it will try to install that, and only try to
 141 fetch the package by name if it is not valid\.
 142 .fi
 143 .RE
 144 .RS 0
 145 .IP \(bu 2
 146 \fBnpm install [@<scope>/]<name>@<tag>\fP:
 147   Install the version of the package that is referenced by the specified tag\.
 148   If the tag does not exist in the registry data for that package, then this
 149   will fail\.
 150   Example:
 151 .P
 152 .RS 2
 153 .nf
 154     npm install sax@latest
 155     npm install @myorg/mypackage@latest
 156 .fi
 157 .RE
 158 .IP \(bu 2
 159 \fBnpm install [@<scope>/]<name>@<version>\fP:
 160   Install the specified version of the package\.  This will fail if the
 161   version has not been published to the registry\.
 162   Example:
 163 .P
 164 .RS 2
 165 .nf
 166     npm install sax@0\.1\.1
 167     npm install @myorg/privatepackage@1\.5\.0
 168 .fi
 169 .RE
 170 .IP \(bu 2
 171 \fBnpm install [@<scope>/]<name>@<version range>\fP:
 172   Install a version of the package matching the specified version range\.  This
 173   will follow the same rules for resolving dependencies described in npm help 5 \fBpackage\.json\fP\|\.
 174   Note that most version ranges must be put in quotes so that your shell will
 175   treat it as a single argument\.
 176   Example:
 177 .P
 178 .RS 2
 179 .nf
 180     npm install sax@">=0\.1\.0 <0\.2\.0"
 181     npm install @myorg/privatepackage@">=0\.1\.0 <0\.2\.0"
 182 .fi
 183 .RE
 184 .IP \(bu 2
 185 \fBnpm install <git remote url>\fP:
 186   Install a package by cloning a git remote url\.  The format of the git
 187   url is:
 188 .P
 189 .RS 2
 190 .nf
 191     <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:/]<path>[#<commit\-ish>]
 192 .fi
 193 .RE
 194   \fB<protocol>\fP is one of \fBgit\fP, \fBgit+ssh\fP, \fBgit+http\fP, or
 195   \fBgit+https\fP\|\.  If no \fB<commit\-ish>\fP is specified, then \fBmaster\fP is
 196   used\.
 197   The following git environment variables are recognized by npm and will be added
 198   to the environment when running git:
 199 .RS 0
 200 .IP \(bu 2
 201 \fBGIT_ASKPASS\fP
 202 .IP \(bu 2
 203 \fBGIT_EXEC_PATH\fP
 204 .IP \(bu 2
 205 \fBGIT_PROXY_COMMAND\fP
 206 .IP \(bu 2
 207 \fBGIT_SSH\fP
 208 .IP \(bu 2
 209 \fBGIT_SSH_COMMAND\fP
 210 .IP \(bu 2
 211 \fBGIT_SSL_CAINFO\fP
 212 .IP \(bu 2
 213 \fBGIT_SSL_NO_VERIFY\fP
 214 See the git man page for details\.
 215 Examples:
 216 .P
 217 .RS 2
 218 .nf
 219 npm install git+ssh://git@github\.com:npm/npm\.git#v1\.0\.27
 220 npm install git+https://isaacs@github\.com/npm/npm\.git
 221 npm install git://github\.com/npm/npm\.git#v1\.0\.27
 222 GIT_SSH_COMMAND='ssh \-i ~/\.ssh/custom_ident' npm install git+ssh://git@github\.com:npm/npm\.git
 223 .fi
 224 .RE
 225
 226 .RE
 227 .IP \(bu 2
 228 \fBnpm install <githubname>/<githubrepo>[#<commit\-ish>]\fP:
 229 .IP \(bu 2
 230 \fBnpm install github:<githubname>/<githubrepo>[#<commit\-ish>]\fP:
 231   Install the package at \fBhttps://github\.com/githubname/githubrepo\fP by
 232   attempting to clone it using \fBgit\fP\|\.
 233   If you don't specify a \fIcommit\-ish\fR then \fBmaster\fP will be used\.
 234   Examples:
 235 .P
 236 .RS 2
 237 .nf
 238     npm install mygithubuser/myproject
 239     npm install github:mygithubuser/myproject
 240 .fi
 241 .RE
 242 .IP \(bu 2
 243 \fBnpm install gist:[<githubname>/]<gistID>[#<commit\-ish>]\fP:
 244   Install the package at \fBhttps://gist\.github\.com/gistID\fP by attempting to
 245   clone it using \fBgit\fP\|\. The GitHub username associated with the gist is
 246   optional and will not be saved in \fBpackage\.json\fP if \fB\-\-save\fP is used\.
 247   If you don't specify a \fIcommit\-ish\fR then \fBmaster\fP will be used\.
 248   Example:
 249 .P
 250 .RS 2
 251 .nf
 252     npm install gist:101a11beef
 253 .fi
 254 .RE
 255 .IP \(bu 2
 256 \fBnpm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit\-ish>]\fP:
 257   Install the package at \fBhttps://bitbucket\.org/bitbucketname/bitbucketrepo\fP
 258   by attempting to clone it using \fBgit\fP\|\.
 259   If you don't specify a \fIcommit\-ish\fR then \fBmaster\fP will be used\.
 260   Example:
 261 .P
 262 .RS 2
 263 .nf
 264     npm install bitbucket:mybitbucketuser/myproject
 265 .fi
 266 .RE
 267 .IP \(bu 2
 268 \fBnpm install gitlab:<gitlabname>/<gitlabrepo>[#<commit\-ish>]\fP:
 269   Install the package at \fBhttps://gitlab\.com/gitlabname/gitlabrepo\fP
 270   by attempting to clone it using \fBgit\fP\|\.
 271   If you don't specify a \fIcommit\-ish\fR then \fBmaster\fP will be used\.
 272   Example:
 273 .P
 274 .RS 2
 275 .nf
 276     npm install gitlab:mygitlabuser/myproject
 277 .fi
 278 .RE
 279
 280 .RE
 281 .P
 282 You may combine multiple arguments, and even multiple types of arguments\.
 283 For example:
 284 .P
 285 .RS 2
 286 .nf
 287 npm install sax@">=0\.1\.0 <0\.2\.0" bench supervisor
 288 .fi
 289 .RE
 290 .P
 291 The \fB\-\-tag\fP argument will apply to all of the specified install targets\. If a
 292 tag with the given name exists, the tagged version is preferred over newer
 293 versions\.
 294 .P
 295 The \fB\-\-force\fP argument will force npm to fetch remote resources even if a
 296 local copy exists on disk\.
 297 .P
 298 .RS 2
 299 .nf
 300 npm install sax \-\-force
 301 .fi
 302 .RE
 303 .P
 304 The \fB\-\-global\fP argument will cause npm to install the package globally
 305 rather than locally\.  See npm help 5 \fBnpm\-folders\fP\|\.
 306 .P
 307 The \fB\-\-ignore\-scripts\fP argument will cause npm to not execute any
 308 scripts defined in the package\.json\. See npm help 7 \fBnpm\-scripts\fP\|\.
 309 .P
 310 The \fB\-\-link\fP argument will cause npm to link global installs into the
 311 local space in some cases\.
 312 .P
 313 The \fB\-\-no\-bin\-links\fP argument will prevent npm from creating symlinks for
 314 any binaries the package might contain\.
 315 .P
 316 The \fB\-\-no\-optional\fP argument will prevent optional dependencies from
 317 being installed\.
 318 .P
 319 The \fB\-\-no\-shrinkwrap\fP argument, which will ignore an available
 320 shrinkwrap file and use the package\.json instead\.
 321 .P
 322 The \fB\-\-nodedir=/path/to/node/source\fP argument will allow npm to find the
 323 node source code so that npm can compile native modules\.
 324 .P
 325 See npm help 7 \fBnpm\-config\fP\|\.  Many of the configuration params have some
 326 effect on installation, since that's most of what npm does\.
 327 .SH ALGORITHM
 328 .P
 329 To install a package, npm uses the following algorithm:
 330 .P
 331 .RS 2
 332 .nf
 333 install(where, what, family, ancestors)
 334 fetch what, unpack to <where>/node_modules/<what>
 335 for each dep in what\.dependencies
 336   resolve dep to precise version
 337 for each dep@version in what\.dependencies
 338     not in <where>/node_modules/<what>/node_modules/*
 339     and not in <family>
 340   add precise version deps to <family>
 341   install(<where>/node_modules/<what>, dep, family)
 342 .fi
 343 .RE
 344 .P
 345 For this \fBpackage{dep}\fP structure: \fBA{B,C}, B{C}, C{D}\fP,
 346 this algorithm produces:
 347 .P
 348 .RS 2
 349 .nf
 350 A
 351 +\-\- B
 352 `\-\- C
 353     `\-\- D
 354 .fi
 355 .RE
 356 .P
 357 That is, the dependency from B to C is satisfied by the fact that A
 358 already caused C to be installed at a higher level\.
 359 .P
 360 See npm help 5 folders for a more detailed description of the specific
 361 folder structures that npm creates\.
 362 .SS Limitations of npm's Install Algorithm
 363 .P
 364 There are some very rare and pathological edge\-cases where a cycle can
 365 cause npm to try to install a never\-ending tree of packages\.  Here is
 366 the simplest case:
 367 .P
 368 .RS 2
 369 .nf
 370 A \-> B \-> A' \-> B' \-> A \-> B \-> A' \-> B' \-> A \-> \.\.\.
 371 .fi
 372 .RE
 373 .P
 374 where \fBA\fP is some version of a package, and \fBA'\fP is a different version
 375 of the same package\.  Because \fBB\fP depends on a different version of \fBA\fP
 376 than the one that is already in the tree, it must install a separate
 377 copy\.  The same is true of \fBA'\fP, which must install \fBB'\fP\|\.  Because \fBB'\fP
 378 depends on the original version of \fBA\fP, which has been overridden, the
 379 cycle falls into infinite regress\.
 380 .P
 381 To avoid this situation, npm flat\-out refuses to install any
 382 \fBname@version\fP that is already present anywhere in the tree of package
 383 folder ancestors\.  A more correct, but more complex, solution would be
 384 to symlink the existing version into the new location\.  If this ever
 385 affects a real use\-case, it will be investigated\.
 386 .SH SEE ALSO
 387 .RS 0
 388 .IP \(bu 2
 389 npm help 5 folders
 390 .IP \(bu 2
 391 npm help update
 392 .IP \(bu 2
 393 npm help link
 394 .IP \(bu 2
 395 npm help rebuild
 396 .IP \(bu 2
 397 npm help 7 scripts
 398 .IP \(bu 2
 399 npm help build
 400 .IP \(bu 2
 401 npm help config
 402 .IP \(bu 2
 403 npm help 7 config
 404 .IP \(bu 2
 405 npm help 5 npmrc
 406 .IP \(bu 2
 407 npm help 7 registry
 408 .IP \(bu 2
 409 npm help tag
 410 .IP \(bu 2
 411 npm help uninstall
 412 .IP \(bu 2
 413 npm help shrinkwrap
 414 .IP \(bu 2
 415 npm help 5 package\.json
 416
 417 .RE
 418