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