deps/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 <name> [--save|--save-dev|--save-optional]
  11     npm install <name>@<tag>
  12     npm install <name>@<version>
  13     npm install <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 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 with (c)
  28 * e) a `<name>@<tag>` 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
  47     dependencies. With the `--production` flag,
  48     npm will not install modules listed in `devDependencies`.
  49
  50 * `npm install <folder>`:
  51
  52     Install a package that is sitting in a folder on the filesystem.
  53
  54 * `npm install <tarball file>`:
  55
  56     Install a package that is sitting on the filesystem.  Note: if you just want
  57     to link a dev directory into your npm root, you can do this more easily by
  58     using `npm link`.
  59
  60     Example:
  61
  62           npm install ./package.tgz
  63
  64 * `npm install <tarball url>`:
  65
  66     Fetch the tarball url, and then install it.  In order to distinguish between
  67     this and other options, the argument must start with "http://" or "https://"
  68
  69     Example:
  70
  71           npm install https://github.com/indexzero/forever/tarball/v0.5.6
  72
  73 * `npm install <name> [--save|--save-dev|--save-optional]`:
  74
  75     Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See
  76     `npm-config(7)`.)
  77
  78     In most cases, this will install the latest version
  79     of the module published on npm.
  80
  81     Example:
  82
  83           npm install sax
  84
  85     `npm install` takes 3 exclusive, optional flags which save or update
  86     the package version in your main package.json:
  87
  88     * `--save`: Package will appear in your `dependencies`.
  89
  90     * `--save-dev`: Package will appear in your `devDependencies`.
  91
  92     * `--save-optional`: Package will appear in your `optionalDependencies`.
  93
  94     Examples:
  95
  96           npm install sax --save
  97           npm install node-tap --save-dev
  98           npm install dtrace-provider --save-optional
  99
 100
 101     **Note**: If there is a file or folder named `<name>` in the current
 102     working directory, then it will try to install that, and only try to
 103     fetch the package by name if it is not valid.
 104
 105 * `npm install <name>@<tag>`:
 106
 107     Install the version of the package that is referenced by the specified tag.
 108     If the tag does not exist in the registry data for that package, then this
 109     will fail.
 110
 111     Example:
 112
 113           npm install sax@latest
 114
 115 * `npm install <name>@<version>`:
 116
 117     Install the specified version of the package.  This will fail if the version
 118     has not been published to the registry.
 119
 120     Example:
 121
 122           npm install sax@0.1.1
 123
 124 * `npm install <name>@<version range>`:
 125
 126     Install a version of the package matching the specified version range.  This
 127     will follow the same rules for resolving dependencies described in `package.json(5)`.
 128
 129     Note that most version ranges must be put in quotes so that your shell will
 130     treat it as a single argument.
 131
 132     Example:
 133
 134           npm install sax@">=0.1.0 <0.2.0"
 135
 136 * `npm install <git remote url>`:
 137
 138     Install a package by cloning a git remote url.  The format of the git
 139     url is:
 140
 141           <protocol>://[<user>@]<hostname><separator><path>[#<commit-ish>]
 142
 143     `<protocol>` is one of `git`, `git+ssh`, `git+http`, or
 144     `git+https`.  If no `<commit-ish>` is specified, then `master` is
 145     used.
 146
 147     Examples:
 148
 149           git+ssh://git@github.com:isaacs/npm.git#v1.0.27
 150           git+https://isaacs@github.com/isaacs/npm.git
 151           git://github.com/isaacs/npm.git#v1.0.27
 152
 153 You may combine multiple arguments, and even multiple types of arguments.
 154 For example:
 155
 156     npm install sax@">=0.1.0 <0.2.0" bench supervisor
 157
 158 The `--tag` argument will apply to all of the specified install targets. If a
 159 tag with the given name exists, the tagged version is preferred over newer
 160 versions.
 161
 162 The `--force` argument will force npm to fetch remote resources even if a
 163 local copy exists on disk.
 164
 165     npm install sax --force
 166
 167 The `--global` argument will cause npm to install the package globally
 168 rather than locally.  See `npm-folders(5)`.
 169
 170 The `--link` argument will cause npm to link global installs into the
 171 local space in some cases.
 172
 173 The `--no-bin-links` argument will prevent npm from creating symlinks for
 174 any binaries the package might contain.
 175
 176 The `--no-shrinkwrap` argument, which will ignore an available
 177 shrinkwrap file and use the package.json instead.
 178
 179 The `--nodedir=/path/to/node/source` argument will allow npm to find the
 180 node source code so that npm can compile native modules.
 181
 182 See `npm-config(7)`.  Many of the configuration params have some
 183 effect on installation, since that's most of what npm does.
 184
 185 ## ALGORITHM
 186
 187 To install a package, npm uses the following algorithm:
 188
 189     install(where, what, family, ancestors)
 190     fetch what, unpack to <where>/node_modules/<what>
 191     for each dep in what.dependencies
 192       resolve dep to precise version
 193     for each dep@version in what.dependencies
 194         not in <where>/node_modules/<what>/node_modules/*
 195         and not in <family>
 196       add precise version deps to <family>
 197       install(<where>/node_modules/<what>, dep, family)
 198
 199 For this `package{dep}` structure: `A{B,C}, B{C}, C{D}`,
 200 this algorithm produces:
 201
 202     A
 203     +-- B
 204     `-- C
 205         `-- D
 206
 207 That is, the dependency from B to C is satisfied by the fact that A
 208 already caused C to be installed at a higher level.
 209
 210 See npm-folders(5) for a more detailed description of the specific
 211 folder structures that npm creates.
 212
 213 ### Limitations of npm's Install Algorithm
 214
 215 There are some very rare and pathological edge-cases where a cycle can
 216 cause npm to try to install a never-ending tree of packages.  Here is
 217 the simplest case:
 218
 219     A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ...
 220
 221 where `A` is some version of a package, and `A'` is a different version
 222 of the same package.  Because `B` depends on a different version of `A`
 223 than the one that is already in the tree, it must install a separate
 224 copy.  The same is true of `A'`, which must install `B'`.  Because `B'`
 225 depends on the original version of `A`, which has been overridden, the
 226 cycle falls into infinite regress.
 227
 228 To avoid this situation, npm flat-out refuses to install any
 229 `name@version` that is already present anywhere in the tree of package
 230 folder ancestors.  A more correct, but more complex, solution would be
 231 to symlink the existing version into the new location.  If this ever
 232 affects a real use-case, it will be investigated.
 233
 234 ## SEE ALSO
 235
 236 * npm-folders(5)
 237 * npm-update(1)
 238 * npm-link(1)
 239 * npm-rebuild(1)
 240 * npm-scripts(7)
 241 * npm-build(1)
 242 * npm-config(1)
 243 * npm-config(7)
 244 * npmrc(5)
 245 * npm-registry(7)
 246 * npm-folders(5)
 247 * npm-tag(1)
 248 * npm-rm(1)
 249 * npm-shrinkwrap(1)