1NPM-DIST-TAG(1)                                                NPM-DIST-TAG(1)
2
3
4

NAME

6       npm-dist-tag - Modify package distribution tags
7
8   Synopsis
9         npm dist-tag add <package-spec (with version)> [<tag>]
10         npm dist-tag rm <package-spec> <tag>
11         npm dist-tag ls [<package-spec>]
12
13         alias: dist-tags
14
15   Description
16       Add, remove, and enumerate distribution tags on a package:
17
18       • add:  Tags  the  specified  version of the package with the specified
19         tag, or the --tag config if not specified. If you have two-factor au‐
20         thentication  on  auth-and-writes  then  you’ll  need  to  include  a
21         one-time password on the command line with --otp <one-time password>,
22         or at the OTP prompt.
23
24       • rm:  Clear  a  tag  that is no longer in use from the package. If you
25         have two-factor authentication on auth-and-writes then you’ll need to
26         include  a one-time password on the command line with --otp <one-time
27         password>, or at the OTP prompt.
28
29       • ls: Show all of the dist-tags for a package, defaulting to the  pack‐
30         age  in  the  current  prefix.  This is the default action if none is
31         specified.
32
33
34       A tag can be used when installing packages as a reference to a  version
35       instead of using a specific version number:
36
37         npm install <name>@<tag>
38
39       When  installing dependencies, a preferred tagged version may be speci‐
40       fied:
41
42         npm install --tag <tag>
43
44       (This also applies to any other commands that resolve and  install  de‐
45       pendencies, such as npm dedupe, npm update, and npm audit fix.)
46
47       Publishing  a  package sets the latest tag to the published version un‐
48       less the --tag option is used. For example, npm publish --tag=beta.
49
50       By default, npm install <pkg> (without any @<version> or @<tag>  speci‐
51       fier) installs the latest tag.
52
53   Purpose
54       Tags can be used to provide an alias instead of version numbers.
55
56       For  example, a project might choose to have multiple streams of devel‐
57       opment and use a different tag for each  stream,  e.g.,  stable,  beta,
58       dev, canary.
59
60       By  default, the latest tag is used by npm to identify the current ver‐
61       sion of a package, and npm install <pkg>  (without  any  @<version>  or
62       @<tag> specifier) installs the latest tag. Typically, projects only use
63       the latest tag for stable release versions, and use other tags for  un‐
64       stable versions such as prereleases.
65
66       The next tag is used by some projects to identify the upcoming version.
67
68       Other than latest, no tag has any special significance to npm itself.
69
70   Caveats
71       This  command used to be known as npm tag, which only created new tags,
72       and so had a different syntax.
73
74       Tags must share a namespace with  version  numbers,  because  they  are
75       specified  in the same slot: npm install <pkg>@<version> vs npm install
76       <pkg>@<tag>.
77
78       Tags that can be interpreted as valid semver ranges will  be  rejected.
79       For example, v1.4 cannot be used as a tag, because it is interpreted by
80       semver as >=1.4.0 <1.5.0.  See https://github.com/npm/npm/issues/6082.
81
82       The simplest way to avoid semver problems with tags is to use tags that
83       do not begin with a number or the letter v.
84
85   Configuration
86   workspace
87       • Default:
88
89       • Type: String (can be set multiple times)
90
91
92       Enable running a command in the context of the configured workspaces of
93       the current project while filtering by running only the workspaces  de‐
94       fined by this configuration option.
95
96       Valid values for the workspace config are either:
97
98       • Workspace names
99
100       • Path to a workspace directory
101
102       • Path  to  a  parent workspace directory (will result in selecting all
103         workspaces within that folder)
104
105
106       When set for the npm init command, this may be set to the folder  of  a
107       workspace  which does not yet exist, to create the folder and set it up
108       as a brand new workspace within the project.
109
110       This value is not exported to the environment for child processes.
111
112   workspaces
113       • Default: null
114
115       • Type: null or Boolean
116
117
118       Set to true to run  the  command  in  the  context  of  all  configured
119       workspaces.
120
121       Explicitly  setting  this  to false will cause commands like install to
122       ignore workspaces altogether. When not set explicitly:
123
124       • Commands that operate on  the  node_modules  tree  (install,  update,
125         etc.)   will link workspaces into the node_modules folder. - Commands
126         that do other things (test, exec, publish, etc.) will operate on  the
127         root  project,  unless  one  or  more workspaces are specified in the
128         workspace config.
129
130
131       This value is not exported to the environment for child processes.
132
133   include-workspace-root
134       • Default: false
135
136       • Type: Boolean
137
138
139       Include the workspace root when workspaces are enabled for a command.
140
141       When false, specifying individual workspaces via the workspace  config,
142       or  all  workspaces  via the workspaces flag, will cause npm to operate
143       only on the specified workspaces, and not on the root project.
144
145       This value is not exported to the environment for child processes.
146
147   See Also
148       • npm help package spec
149
150       • npm help publish
151
152       • npm help install
153
154       • npm help dedupe
155
156       • npm help registry
157
158       • npm help config
159
160       • npm help npmrc
161
162
163
164
165                                September 2022                 NPM-DIST-TAG(1)
Impressum