1PACKAGE-SPEC(7)                                                PACKAGE-SPEC(7)
2
3
4

NAME

6       package-spec - Package name specifier
7
8   Description
9       Commands  like  npm  install  and  the dependency sections in the pack‐
10       age.json use a package name  specifier.  This  can  be  many  different
11       things  that all refer to a "package". Examples include a package name,
12       git url, tarball, or local directory. These will generally be  referred
13       to  as  <package-spec> in the help output for the npm commands that use
14       this package name specifier.
15
16   Package name
17       •   [<@scope>/]<pkg>
18
19       •   [<@scope>/]<pkg>@<tag>
20
21       •   [<@scope>/]<pkg>@<version>
22
23       •   [<@scope>/]<pkg>@<version range>
24
25
26       Refers to a package by name, with or without a  scope,  and  optionally
27       tag,  version,  or version range. This is typically used in combination
28       with the registry ⟨/using-npm/config#registry⟩ config  to  refer  to  a
29       package in a registry.
30
31       Examples:
32
33       •   npm
34
35       •   @npmcli/arborist
36
37       •   @npmcli/arborist@latest
38
39       •   npm@6.13.1
40
41       •   npm@^4.0.0
42
43
44   Aliases
45       •   <alias>@npm:<name>
46
47
48       Primarily  used by commands like npm install and in the dependency sec‐
49       tions in the package.json, this refers to a package by  an  alias.  The
50       <alias> is the name of the package as it is reified in the node_modules
51       folder, and the <name> refers to a package name as found in the config‐
52       ured registry.
53
54       See Package name above for more info on referring to a package by name,
55       and registry ⟨/using-npm/config#registry⟩ for  configuring  which  reg‐
56       istry is used when referring to a package by name.
57
58       Examples:
59
60       •   semver:@npm:@npmcli/semver-with-patch
61
62       •   semver:@npm:semver@7.2.2
63
64       •   semver:@npm:semver@legacy
65
66
67   Folders
68       •   <folder>
69
70
71       This  refers to a package on the local filesystem. Specifically this is
72       a folder with a package.json file in it. This should always be prefixed
73       with  a  /  or ./ (or your OS equivalent) to reduce confusion. npm cur‐
74       rently will parse a string with more than one / in it as a folder,  but
75       this is legacy behavior that may be removed in a future version.
76
77       Examples:
78
79       •   ./my-package
80
81       •   /opt/npm/my-package
82
83
84   Tarballs
85       •   <tarball file>
86
87       •   <tarball url>
88
89
90       Examples:
91
92       •   ./my-package.tgz
93
94       •   https://registry.npmjs.org/semver/-/semver-1.0.0.tgz
95
96
97       Refers to a package in a tarball format, either on the local filesystem
98       or remotely via url. This is the format that packages exist in when up‐
99       loaded to a registry.
100
101   git urls
102       •   <git:// url>
103
104       •   <github username>/<github project>
105
106
107       Refers  to  a  package  in  a git repo. This can be a full git url, git
108       shorthand, or a username/package on GitHub. You can specify a git  tag,
109       branch, or other git ref by appending #ref.
110
111       Examples:
112
113       •   https://github.com/npm/cli.git
114
115       •   git@github.com:npm/cli.git
116
117       •   git+ssh://git@github.com/npm/cli#v6.0.0
118
119       •   github:npm/cli#HEAD
120
121       •   npm/cli#c12ea07
122
123
124   See also
125       •   npm-package-arg ⟨https://npm.im/npm-package-arg⟩
126
127       •   npm help scope
128
129       •   npm help config
130
131
132
133                                 November 2023                 PACKAGE-SPEC(7)