org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/doc/cli/npm-install.md

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