1 npm-install(1) -- Install a package
2 ===================================
6 npm install (with no args in a package dir)
7 npm install <tarball file>
8 npm install <tarball url>
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)
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).
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)
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).
38 * `npm install` (in package directory, no arguments):
40 Install the dependencies in the local node_modules folder.
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.
46 By default, `npm install` will install all modules listed as dependencies
49 With the `--production` flag (or when the `NODE_ENV` environment variable
50 is set to `production`), npm will not install modules listed in
53 * `npm install <folder>`:
55 Install a package that is sitting in a folder on the filesystem.
57 * `npm install <tarball file>`:
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
65 npm install ./package.tgz
67 * `npm install <tarball url>`:
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://"
74 npm install https://github.com/indexzero/forever/tarball/v0.5.6
76 * `npm install [@<scope>/]<name> [--save|--save-dev|--save-optional]`:
78 Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See
79 `npm-config(7)`. The config's default value is `latest`.)
81 In most cases, this will install the latest version
82 of the module published on npm.
88 `npm install` takes 3 exclusive, optional flags which save or update
89 the package version in your main package.json:
91 * `--save`: Package will appear in your `dependencies`.
93 * `--save-dev`: Package will appear in your `devDependencies`.
95 * `--save-optional`: Package will appear in your `optionalDependencies`.
97 When using any of the above options to save dependencies to your
98 package.json, there are two additional, optional flags:
100 * `--save-exact`: Saved dependencies will be configured with an
101 exact version rather than using npm's default semver range
104 * `-B, --save-bundle`: Saved dependencies will also be added to your `bundleDependencies` list.
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.
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
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.
125 * `npm install [@<scope>/]<name>@<tag>`:
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
133 npm install sax@latest
134 npm install @myorg/mypackage@latest
136 * `npm install [@<scope>/]<name>@<version>`:
138 Install the specified version of the package. This will fail if the
139 version has not been published to the registry.
143 npm install sax@0.1.1
144 npm install @myorg/privatepackage@1.5.0
146 * `npm install [@<scope>/]<name>@<version range>`:
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)`.
151 Note that most version ranges must be put in quotes so that your shell will
152 treat it as a single argument.
156 npm install sax@">=0.1.0 <0.2.0"
157 npm install @myorg/privatepackage@">=0.1.0 <0.2.0"
159 * `npm install <git remote url>`:
161 Install a package by cloning a git remote url. The format of the git
164 <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:/]<path>[#<commit-ish>]
166 `<protocol>` is one of `git`, `git+ssh`, `git+http`, or
167 `git+https`. If no `<commit-ish>` is specified, then `master` is
170 The following git environment variables are recognized by npm and will be added
171 to the environment when running git:
175 * `GIT_PROXY_COMMAND`
179 * `GIT_SSL_NO_VERIFY`
181 See the git man page for details.
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
190 * `npm install <githubname>/<githubrepo>[#<commit-ish>]`:
191 * `npm install github:<githubname>/<githubrepo>[#<commit-ish>]`:
193 Install the package at `https://github.com/githubname/githubrepo` by
194 attempting to clone it using `git`.
196 If you don't specify a *commit-ish* then `master` will be used.
200 npm install mygithubuser/myproject
201 npm install github:mygithubuser/myproject
203 * `npm install gist:[<githubname>/]<gistID>[#<commit-ish>]`:
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.
209 If you don't specify a *commit-ish* then `master` will be used.
213 npm install gist:101a11beef
215 * `npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]`:
217 Install the package at `https://bitbucket.org/bitbucketname/bitbucketrepo`
218 by attempting to clone it using `git`.
220 If you don't specify a *commit-ish* then `master` will be used.
224 npm install bitbucket:mybitbucketuser/myproject
226 * `npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]`:
228 Install the package at `https://gitlab.com/gitlabname/gitlabrepo`
229 by attempting to clone it using `git`.
231 If you don't specify a *commit-ish* then `master` will be used.
235 npm install gitlab:mygitlabuser/myproject
237 You may combine multiple arguments, and even multiple types of arguments.
240 npm install sax@">=0.1.0 <0.2.0" bench supervisor
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
246 The `--force` argument will force npm to fetch remote resources even if a
247 local copy exists on disk.
249 npm install sax --force
251 The `--global` argument will cause npm to install the package globally
252 rather than locally. See `npm-folders(5)`.
254 The `--ignore-scripts` argument will cause npm to not execute any
255 scripts defined in the package.json. See `npm-scripts(7)`.
257 The `--link` argument will cause npm to link global installs into the
258 local space in some cases.
260 The `--no-bin-links` argument will prevent npm from creating symlinks for
261 any binaries the package might contain.
263 The `--no-optional` argument will prevent optional dependencies from
266 The `--no-shrinkwrap` argument, which will ignore an available
267 shrinkwrap file and use the package.json instead.
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.
272 See `npm-config(7)`. Many of the configuration params have some
273 effect on installation, since that's most of what npm does.
277 To install a package, npm uses the following algorithm:
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/*
286 add precise version deps to <family>
287 install(<where>/node_modules/<what>, dep, family)
289 For this `package{dep}` structure: `A{B,C}, B{C}, C{D}`,
290 this algorithm produces:
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.
300 See npm-folders(5) for a more detailed description of the specific
301 folder structures that npm creates.
303 ### Limitations of npm's Install Algorithm
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
309 A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ...
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.
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.