@cryptotaxi247 / documentation-1
Code Commits Issues Pulls Sessions CI/CD
jpg619/fix-accessibility-content-flow
@reggi/path-to-regexp dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2 dependabot/npm_and_yarn/main/eslint-10.4.0 dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0 dependabot/npm_and_yarn/main/proc-log-7.0.0 dependabot/npm_and_yarn/npm_and_yarn-826852524d dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2 deprecate-totp-2fa dhei/classic-tokens gat-bypass-2fa-docs jpg619/fix-accessibility-content-flow jpg619/version-bump-tar-2 kartykp/gat-bypass-2fa-docs kartykp/upgrade-path-to-regex main maitxn/version-bump-tar patch-1 reggi/cache-based-on-version reggi/dev-engines reggi/fix-transform-prettier reggi/overrides update-search-sensitivity
mdx 501 lines 21.3 KB
Raw
1 ---
2 title: npm-install
3 section: 1
4 description: Install a package
5 github_repo: npm/cli
6 github_branch: release/v7
7 github_path: docs/content/commands/npm-install.md
8 redirect_from:
9 - /cli-documentation/v7/cli-commands/install
10 - /cli-documentation/v7/cli-commands/npm-install
11 - /cli-documentation/v7/commands/install
12 - /cli-documentation/v7/commands/npm-install
13 - /cli-documentation/v7/install
14 - /cli-documentation/v7/npm-install
15 - /cli/v7/cli-commands/install
16 - /cli/v7/cli-commands/npm-install
17 - /cli/v7/commands/install
18 - /cli/v7/install
19 - /cli/v7/npm-install
20 ---
21
22 ### Synopsis
23
24 ```bash
25 npm install (with no args, in package dir)
26 npm install [<@scope>/]<name>
27 npm install [<@scope>/]<name>@<tag>
28 npm install [<@scope>/]<name>@<version>
29 npm install [<@scope>/]<name>@<version range>
30 npm install <alias>@npm:<name>
31 npm install <git-host>:<git-user>/<repo-name>
32 npm install <git repo url>
33 npm install <tarball file>
34 npm install <tarball url>
35 npm install <folder>
36
37 aliases: npm i, npm add
38 common options: [-P|--save-prod|-D|--save-dev|-O|--save-optional|--save-peer] [-E|--save-exact] [-B|--save-bundle] [--no-save] [--dry-run]
39 ```
40
41 ### Description
42
43 This command installs a package and any packages that it depends on. If the package has a package-lock, or an npm shrinkwrap file, or a yarn lock file, the installation of dependencies will be driven by that, respecting the following order of precedence:
44
45 - `npm-shrinkwrap.json`
46 - `package-lock.json`
47 - `yarn.lock`
48
49 See [package-lock.json](/cli/v7/configuring-npm/package-lock-json) and [`npm shrinkwrap`](/cli/v7/commands/npm-shrinkwrap).
50
51 A `package` is:
52
53 - a) a folder containing a program described by a [`package.json`](/cli/v7/configuring-npm/package-json) file
54 - b) a gzipped tarball containing (a)
55 - c) a url that resolves to (b)
56 - d) a `<name>@<version>` that is published on the registry (see [`registry`](/cli/v7/using-npm/registry)) with (c)
57 - e) a `<name>@<tag>` (see [`npm dist-tag`](/cli/v7/commands/npm-dist-tag)) that points to (d)
58 - f) a `<name>` that has a "latest" tag satisfying (e)
59 - g) a `<git remote url>` that resolves to (a)
60
61 Even if you never publish your package, you can still get a lot of benefits of using npm if you just want to write a node program (a), and perhaps if you also want to be able to easily install it elsewhere after packing it up into a tarball (b).
62
63 - `npm install` (in a package directory, no arguments):
64
65 Install the dependencies in the local `node_modules` folder.
66
67 In global mode (ie, with `-g` or `--global` appended to the command), it installs the current package context (ie, the current working directory) as a global package.
68
69 By default, `npm install` will install all modules listed as dependencies in [`package.json`](/cli/v7/configuring-npm/package-json).
70
71 With the `--production` flag (or when the `NODE_ENV` environment variable is set to `production`), npm will not install modules listed in `devDependencies`. To install all modules listed in both `dependencies` and `devDependencies` when `NODE_ENV` environment variable is set to `production`, you can use `--production=false`.
72
73 > NOTE: The `--production` flag has no particular meaning when adding a dependency to a project.
74
75 - `npm install <folder>`:
76
77 Install the package in the directory as a symlink in the current project. Its dependencies will be installed before it's linked. If `<folder>` sits inside the root of your project, its dependencies may be hoisted to the top-level `node_modules` as they would for other types of dependencies.
78
79 - `npm install <tarball file>`:
80
81 Install a package that is sitting on the filesystem. Note: if you just want to link a dev directory into your npm root, you can do this more easily by using [`npm link`](/cli/v7/commands/npm-link).
82
83 Tarball requirements:
84 - The filename _must_ use `.tar`, `.tar.gz`, or `.tgz` as the extension.
85 - The package contents should reside in a subfolder inside the tarball (usually it is called `package/`). npm strips one directory layer when installing the package (an equivalent of `tar x --strip-components=1` is run).
86 - The package must contain a `package.json` file with `name` and `version` properties.
87
88 Example:
89
90 ```bash
91 npm install ./package.tgz
92 ```
93
94 - `npm install <tarball url>`:
95
96 Fetch the tarball url, and then install it. In order to distinguish between this and other options, the argument must start with "http://" or "https://"
97
98 Example:
99
100 ```bash
101 npm install https://github.com/indexzero/forever/tarball/v0.5.6
102 ```
103
104 - `npm install [<@scope>/]<name>`:
105
106 Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See [`config`](/cli/v7/using-npm/config). The config's default value is `latest`.)
107
108 In most cases, this will install the version of the modules tagged as `latest` on the npm registry.
109
110 Example:
111
112 ```bash
113 npm install sax
114 ```
115
116 `npm install` saves any specified packages into `dependencies` by default. Additionally, you can control where and how they get saved with some additional flags:
117 - `-P, --save-prod`: Package will appear in your `dependencies`. This is the default unless `-D` or `-O` are present.
118
119 - `-D, --save-dev`: Package will appear in your `devDependencies`.
120
121 - `-O, --save-optional`: Package will appear in your `optionalDependencies`.
122
123 - `--no-save`: Prevents saving to `dependencies`.
124
125 When using any of the above options to save dependencies to your package.json, there are two additional, optional flags:
126 - `-E, --save-exact`: Saved dependencies will be configured with an exact version rather than using npm's default semver range operator.
127
128 - `-B, --save-bundle`: Saved dependencies will also be added to your `bundleDependencies` list.
129
130 Further, if you have an `npm-shrinkwrap.json` or `package-lock.json` then it will be updated as well.
131
132 `<scope>` is optional. The package will be downloaded from the registry associated with the specified scope. If no registry is associated with the given scope the default registry is assumed. See [`scope`](/cli/v7/using-npm/scope).
133
134 Note: if you do not include the @-symbol on your scope name, npm will interpret this as a GitHub repository instead, see below. Scopes names must also be followed by a slash.
135
136 Examples:
137
138 ```bash
139 npm install sax
140 npm install githubname/reponame
141 npm install @myorg/privatepackage
142 npm install node-tap --save-dev
143 npm install dtrace-provider --save-optional
144 npm install readable-stream --save-exact
145 npm install ansi-regex --save-bundle
146 ```
147
148 **Note**: If there is a file or folder named `<name>` in the current working directory, then it will try to install that, and only try to fetch the package by name if it is not valid.
149
150 - `npm install <alias>@npm:<name>`:
151
152 Install a package under a custom alias. Allows multiple versions of a same-name package side-by-side, more convenient import names for packages with otherwise long ones, and using git forks replacements or forked npm packages as replacements. Aliasing works only on your project and does not rename packages in transitive dependencies. Aliases should follow the naming conventions stated in [`validate-npm-package-name`](https://www.npmjs.com/package/validate-npm-package-name#naming-rules).
153
154 Examples:
155
156 ```bash
157 npm install my-react@npm:react
158 npm install jquery2@npm:jquery@2
159 npm install jquery3@npm:jquery@3
160 npm install npa@npm:npm-package-arg
161 ```
162
163 - `npm install [<@scope>/]<name>@<tag>`:
164
165 Install the version of the package that is referenced by the specified tag. If the tag does not exist in the registry data for that package, then this will fail.
166
167 Example:
168
169 ```bash
170 npm install sax@latest
171 npm install @myorg/mypackage@latest
172 ```
173
174 - `npm install [<@scope>/]<name>@<version>`:
175
176 Install the specified version of the package. This will fail if the version has not been published to the registry.
177
178 Example:
179
180 ```bash
181 npm install sax@0.1.1
182 npm install @myorg/privatepackage@1.5.0
183 ```
184
185 - `npm install [<@scope>/]<name>@<version range>`:
186
187 Install a version of the package matching the specified version range. This will follow the same rules for resolving dependencies described in [`package.json`](/cli/v7/configuring-npm/package-json).
188
189 Note that most version ranges must be put in quotes so that your shell will treat it as a single argument.
190
191 Example:
192
193 ```bash
194 npm install sax@">=0.1.0 <0.2.0"
195 npm install @myorg/privatepackage@"16 - 17"
196 ```
197
198 - `npm install <git remote url>`:
199
200 Installs the package from the hosted git provider, cloning it with `git`. For a full git remote url, only that URL will be attempted.
201
202 ```bash
203 <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
204 ```
205
206 `<protocol>` is one of `git`, `git+ssh`, `git+http`, `git+https`, or `git+file`.
207
208 If `#<commit-ish>` is provided, it will be used to clone exactly that commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is specified, then the default branch of the repository is used.
209
210 If the repository makes use of submodules, those submodules will be cloned as well.
211
212 If the package being installed contains a `prepare` script, its `dependencies` and `devDependencies` will be installed, and the prepare script will be run, before the package is packaged and installed.
213
214 The following git environment variables are recognized by npm and will be added to the environment when running git:
215 - `GIT_ASKPASS`
216 - `GIT_EXEC_PATH`
217 - `GIT_PROXY_COMMAND`
218 - `GIT_SSH`
219 - `GIT_SSH_COMMAND`
220 - `GIT_SSL_CAINFO`
221 - `GIT_SSL_NO_VERIFY`
222
223 See the git man page for details.
224
225 Examples:
226
227 ```bash
228 npm install git+ssh://git@github.com:npm/cli.git#v1.0.27
229 npm install git+ssh://git@github.com:npm/cli#pull/273
230 npm install git+ssh://git@github.com:npm/cli#semver:^5.0
231 npm install git+https://isaacs@github.com/npm/cli.git
232 npm install git://github.com/npm/cli.git#v1.0.27
233 GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/cli.git
234 ```
235
236 - `npm install <githubname>/<githubrepo>[#<commit-ish>]`:
237 - `npm install github:<githubname>/<githubrepo>[#<commit-ish>]`:
238
239 Install the package at `https://github.com/githubname/githubrepo` by attempting to clone it using `git`.
240
241 If `#<commit-ish>` is provided, it will be used to clone exactly that commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is specified, then `master` is used.
242
243 As with regular git dependencies, `dependencies` and `devDependencies` will be installed if the package has a `prepare` script before the package is done installing.
244
245 Examples:
246
247 ```bash
248 npm install mygithubuser/myproject
249 npm install github:mygithubuser/myproject
250 ```
251
252 - `npm install gist:[<githubname>/]<gistID>[#<commit-ish>|#semver:<semver>]`:
253
254 Install the package at `https://gist.github.com/gistID` by attempting to clone it using `git`. The GitHub username associated with the gist is optional and will not be saved in `package.json`.
255
256 As with regular git dependencies, `dependencies` and `devDependencies` will be installed if the package has a `prepare` script before the package is done installing.
257
258 Example:
259
260 ```bash
261 npm install gist:101a11beef
262 ```
263
264 - `npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]`:
265
266 Install the package at `https://bitbucket.org/bitbucketname/bitbucketrepo` by attempting to clone it using `git`.
267
268 If `#<commit-ish>` is provided, it will be used to clone exactly that commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is specified, then `master` is used.
269
270 As with regular git dependencies, `dependencies` and `devDependencies` will be installed if the package has a `prepare` script before the package is done installing.
271
272 Example:
273
274 ```bash
275 npm install bitbucket:mybitbucketuser/myproject
276 ```
277
278 - `npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]`:
279
280 Install the package at `https://gitlab.com/gitlabname/gitlabrepo` by attempting to clone it using `git`.
281
282 If `#<commit-ish>` is provided, it will be used to clone exactly that commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is specified, then `master` is used.
283
284 As with regular git dependencies, `dependencies` and `devDependencies` will be installed if the package has a `prepare` script before the package is done installing.
285
286 Example:
287
288 ```bash
289 npm install gitlab:mygitlabuser/myproject
290 npm install gitlab:myusr/myproj#semver:^5.0
291 ```
292
293 You may combine multiple arguments and even multiple types of arguments. For example:
294
295 ```bash
296 npm install sax@">=0.1.0 <0.2.0" bench supervisor
297 ```
298
299 The `--tag` argument will apply to all of the specified install targets. If a tag with the given name exists, the tagged version is preferred over newer versions.
300
301 The `--dry-run` argument will report in the usual way what the install would have done without actually installing anything.
302
303 The `--package-lock-only` argument will only update the `package-lock.json`, instead of checking `node_modules` and downloading dependencies.
304
305 The `-f` or `--force` argument will force npm to fetch remote resources even if a local copy exists on disk.
306
307 ```bash
308 npm install sax --force
309 ```
310
311 ### Configuration
312
313 See the [`config`](/cli/v7/using-npm/config) help doc. Many of the configuration params have some effect on installation, since that's most of what npm does.
314
315 These are some of the most common options related to installation.
316
317 #### `save`
318
319 - Default: true
320 - Type: Boolean
321
322 Save installed packages to a package.json file as dependencies.
323
324 When used with the `npm rm` command, removes the dependency from package.json.
325
326 #### `save-exact`
327
328 - Default: false
329 - Type: Boolean
330
331 Dependencies saved to package.json will be configured with an exact version rather than using npm's default semver range operator.
332
333 #### `global`
334
335 - Default: false
336 - Type: Boolean
337
338 Operates in "global" mode, so that packages are installed into the `prefix` folder instead of the current working directory. See [folders](/cli/v7/configuring-npm/folders) for more on the differences in behavior.
339
340 - packages are installed into the `{prefix}/lib/node_modules` folder, instead of the current working directory.
341 - bin files are linked to `{prefix}/bin`
342 - man pages are linked to `{prefix}/share/man`
343
344 #### `global-style`
345
346 - Default: false
347 - Type: Boolean
348
349 Causes npm to install the package into your local `node_modules` folder with the same layout it uses with the global `node_modules` folder. Only your direct dependencies will show in `node_modules` and everything they depend on will be flattened in their `node_modules` folders. This obviously will eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` will be preferred.
350
351 #### `legacy-bundling`
352
353 - Default: false
354 - Type: Boolean
355
356 Causes npm to install the package such that versions of npm prior to 1.4, such as the one included with node 0.8, can install the package. This eliminates all automatic deduping. If used with `global-style` this option will be preferred.
357
358 #### `strict-peer-deps`
359
360 - Default: false
361 - Type: Boolean
362
363 If set to `true`, and `--legacy-peer-deps` is not set, then _any_ conflicting `peerDependencies` will be treated as an install failure, even if npm could reasonably guess the appropriate resolution based on non-peer dependency relationships.
364
365 By default, conflicting `peerDependencies` deep in the dependency graph will be resolved using the nearest non-peer dependency specification, even if doing so will result in some packages receiving a peer dependency outside the range set in their package's `peerDependencies` object.
366
367 When such and override is performed, a warning is printed, explaining the conflict and the packages involved. If `--strict-peer-deps` is set, then this warning is treated as a failure.
368
369 #### `package-lock`
370
371 - Default: true
372 - Type: Boolean
373
374 If set to false, then ignore `package-lock.json` files when installing. This will also prevent _writing_ `package-lock.json` if `save` is true.
375
376 When package package-locks are disabled, automatic pruning of extraneous modules will also be disabled. To remove extraneous modules with package-locks disabled use `npm prune`.
377
378 #### `omit`
379
380 - Default: 'dev' if the `NODE_ENV` environment variable is set to 'production', otherwise empty.
381 - Type: "dev", "optional", or "peer" (can be set multiple times)
382
383 Dependency types to omit from the installation tree on disk.
384
385 Note that these dependencies _are_ still resolved and added to the `package-lock.json` or `npm-shrinkwrap.json` file. They are just not physically installed on disk.
386
387 If a package type appears in both the `--include` and `--omit` lists, then it will be included.
388
389 If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment variable will be set to `'production'` for all lifecycle scripts.
390
391 #### `ignore-scripts`
392
393 - Default: false
394 - Type: Boolean
395
396 If true, npm does not run scripts specified in package.json files.
397
398 Note that commands explicitly intended to run a particular script, such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` will still run their intended script if `ignore-scripts` is set, but they will _not_ run any pre- or post-scripts.
399
400 #### `audit`
401
402 - Default: true
403 - Type: Boolean
404
405 When "true" submit audit reports alongside the current npm command to the default registry and all registries configured for scopes. See the documentation for [`npm audit`](/cli/v7/commands/npm-audit) for details on what is submitted.
406
407 #### `bin-links`
408
409 - Default: true
410 - Type: Boolean
411
412 Tells npm to create symlinks (or `.cmd` shims on Windows) for package executables.
413
414 Set to false to have it not do this. This can be used to work around the fact that some file systems don't support symlinks, even on ostensibly Unix systems.
415
416 #### `fund`
417
418 - Default: true
419 - Type: Boolean
420
421 When "true" displays the message at the end of each `npm install` acknowledging the number of dependencies looking for funding. See [`npm fund`](/cli/v7/commands/npm-fund) for details.
422
423 #### `dry-run`
424
425 - Default: false
426 - Type: Boolean
427
428 Indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, `install`, `update`, `dedupe`, `uninstall`, as well as `pack` and `publish`.
429
430 Note: This is NOT honored by other network related commands, eg `dist-tags`, `owner`, etc.
431
432 #### `workspace`
433
434 - Default:
435 - Type: String (can be set multiple times)
436
437 Enable running a command in the context of the configured workspaces of the current project while filtering by running only the workspaces defined by this configuration option.
438
439 Valid values for the `workspace` config are either:
440
441 - Workspace names
442 - Path to a workspace directory
443 - Path to a parent workspace directory (will result to selecting all of the nested workspaces)
444
445 When set for the `npm init` command, this may be set to the folder of a workspace which does not yet exist, to create the folder and set it up as a brand new workspace within the project.
446
447 This value is not exported to the environment for child processes.
448
449 #### `workspaces`
450
451 - Default: false
452 - Type: Boolean
453
454 Enable running a command in the context of **all** the configured workspaces.
455
456 This value is not exported to the environment for child processes.
457
458 ### Algorithm
459
460 Given a `package{dep}` structure: `A{B,C}, B{C}, C{D}`, the npm install algorithm produces:
461
462 ```bash
463 A
464 +-- B
465 +-- C
466 +-- D
467 ```
468
469 That is, the dependency from B to C is satisfied by the fact that A already caused C to be installed at a higher level. D is still installed at the top level because nothing conflicts with it.
470
471 For `A{B,C}, B{C,D@1}, C{D@2}`, this algorithm produces:
472
473 ```bash
474 A
475 +-- B
476 +-- C
477 `-- D@2
478 +-- D@1
479 ```
480
481 Because B's D@1 will be installed in the top-level, C now has to install D@2 privately for itself. This algorithm is deterministic, but different trees may be produced if two dependencies are requested for installation in a different order.
482
483 See [folders](/cli/v7/configuring-npm/folders) for a more detailed description of the specific folder structures that npm creates.
484
485 ### See Also
486
487 - [npm folders](/cli/v7/configuring-npm/folders)
488 - [npm update](/cli/v7/commands/npm-update)
489 - [npm audit](/cli/v7/commands/npm-audit)
490 - [npm fund](/cli/v7/commands/npm-fund)
491 - [npm link](/cli/v7/commands/npm-link)
492 - [npm rebuild](/cli/v7/commands/npm-rebuild)
493 - [npm scripts](/cli/v7/using-npm/scripts)
494 - [npm config](/cli/v7/commands/npm-config)
495 - [npmrc](/cli/v7/configuring-npm/npmrc)
496 - [npm registry](/cli/v7/using-npm/registry)
497 - [npm dist-tag](/cli/v7/commands/npm-dist-tag)
498 - [npm uninstall](/cli/v7/commands/npm-uninstall)
499 - [npm shrinkwrap](/cli/v7/commands/npm-shrinkwrap)
500 - [package.json](/cli/v7/configuring-npm/package-json)
501 - [workspaces](/cli/v7/using-npm/workspaces)