2021-11-18 20:58:02 +00:00
<!DOCTYPE html> < html > < head >
< meta charset = "utf-8" >
2020-11-01 07:54:36 +01:00
< title > npm-exec< / title >
< style >
body {
background-color: #ffffff;
color: #24292e;
margin: 0;
line-height: 1.5;
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
}
#rainbar {
height: 10px;
background-image: linear-gradient(139deg, #fb8817, #ff4b01, #c12127, #e02aff);
}
a {
text-decoration: none;
color: #0366d6;
}
a:hover {
text-decoration: underline;
}
pre {
margin: 1em 0px;
padding: 1em;
border: solid 1px #e1e4e8;
border-radius: 6px;
display: block;
overflow: auto;
white-space: pre;
background-color: #f6f8fa;
color: #393a34;
}
code {
font-family: SFMono-Regular, Consolas, "Liberation Mono", Menlo, Courier, monospace;
font-size: 85%;
padding: 0.2em 0.4em;
background-color: #f6f8fa;
color: #393a34;
}
pre > code {
padding: 0;
background-color: inherit;
color: inherit;
}
h1, h2, h3 {
font-weight: 600;
}
#logobar {
background-color: #333333;
margin: 0 auto;
padding: 1em 4em;
}
#logobar .logo {
float: left;
}
#logobar .title {
font-weight: 600;
color: #dddddd;
float: left;
margin: 5px 0 0 1em;
}
#logobar:after {
content: "";
display: block;
clear: both;
}
#content {
margin: 0 auto;
padding: 0 4em;
}
#table_of_contents > h2 {
font-size: 1.17em;
}
#table_of_contents ul:first-child {
border: solid 1px #e1e4e8;
border-radius: 6px;
padding: 1em;
background-color: #f6f8fa;
color: #393a34;
}
#table_of_contents ul {
list-style-type: none;
padding-left: 1.5em;
}
#table_of_contents li {
font-size: 0.9em;
}
#table_of_contents li a {
color: #000000;
}
header.title {
border-bottom: solid 1px #e1e4e8;
}
header.title > h1 {
margin-bottom: 0.25em;
}
header.title > .description {
display: block;
margin-bottom: 0.5em;
line-height: 1;
}
2024-05-16 05:38:49 -07:00
header.title .version {
font-size: 0.8em;
color: #666666;
}
2020-11-01 07:54:36 +01:00
footer#edit {
border-top: solid 1px #e1e4e8;
margin: 3em 0 4em 0;
padding-top: 2em;
}
< / style >
< / head >
< body >
< div id = "banner" >
< div id = "rainbar" > < / div >
< div id = "logobar" >
< svg class = "logo" role = "img" height = "32" width = "32" viewBox = "0 0 700 700" >
< polygon fill = "#cb0000" points = "0,700 700,700 700,0 0,0" > < / polygon >
< polygon fill = "#ffffff" points = "150,550 350,550 350,250 450,250 450,550 550,550 550,150 150,150" > < / polygon >
< / svg >
< div class = "title" >
npm command-line interface
< / div >
< / div >
< / div >
< section id = "content" >
< header class = "title" >
2025-04-10 14:36:22 -07:00
< h1 id = "----npm-exec----1130" >
2024-05-16 05:38:49 -07:00
< span > npm-exec< / span >
2025-04-10 14:36:22 -07:00
< span class = "version" > @11.3.0< / span >
2024-05-16 05:38:49 -07:00
< / h1 >
2020-11-01 07:54:36 +01:00
< span class = "description" > Run a command from a local or remote npm package< / span >
< / header >
< section id = "table_of_contents" >
< h2 id = "table-of-contents" > Table of contents< / h2 >
2021-10-14 22:17:47 +00:00
< div id = "_table_of_contents" > < ul > < li > < a href = "#synopsis" > Synopsis< / a > < / li > < li > < a href = "#description" > Description< / a > < / li > < li > < a href = "#npx-vs-npm-exec" > < code > npx< / code > vs < code > npm exec< / code > < / a > < / li > < li > < a href = "#configuration" > Configuration< / a > < / li > < ul > < li > < a href = "#package" > < code > package< / code > < / a > < / li > < li > < a href = "#call" > < code > call< / code > < / a > < / li > < li > < a href = "#workspace" > < code > workspace< / code > < / a > < / li > < li > < a href = "#workspaces" > < code > workspaces< / code > < / a > < / li > < li > < a href = "#include-workspace-root" > < code > include-workspace-root< / code > < / a > < / li > < / ul > < li > < a href = "#examples" > Examples< / a > < / li > < li > < a href = "#workspaces-support" > Workspaces support< / a > < / li > < ul > < li > < a href = "#filtering-workspaces" > Filtering workspaces< / a > < / li > < / ul > < li > < a href = "#compatibility-with-older-npx-versions" > Compatibility with Older npx Versions< / a > < / li > < li > < a href = "#a-note-on-caching" > A note on caching< / a > < / li > < ul > < li > < a href = "#prefer-online" > prefer-online< / a > < / li > < li > < a href = "#prefer-offline" > prefer-offline< / a > < / li > < li > < a href = "#offline" > offline< / a > < / li > < li > < a href = "#workspace2" > workspace< / a > < / li > < li > < a href = "#workspaces2" > workspaces< / a > < / li > < / ul > < li > < a href = "#see-also" > See Also< / a > < / li > < / ul > < / div >
2020-11-01 07:54:36 +01:00
< / section >
< div id = "_content" > < h3 id = "synopsis" > Synopsis< / h3 >
2022-12-06 22:18:33 -05:00
< pre > < code class = "language-bash" > npm exec -- < pkg> [@< version> ] [args...]
2020-11-01 07:54:36 +01:00
npm exec --package=< pkg> [@< version> ] -- < cmd> [args...]
npm exec -c '< cmd> [args...]'
npm exec --package=foo -c '< cmd> [args...]'
2022-02-24 21:41:49 +00:00
alias: x
2020-11-01 07:54:36 +01:00
< / code > < / pre >
< h3 id = "description" > Description< / h3 >
< p > This command allows you to run an arbitrary command from an npm package
(either one installed locally, or fetched remotely), in a similar context
as running it via < code > npm run< / code > .< / p >
2020-12-04 15:51:55 -05:00
< p > Run without positional arguments or < code > --call< / code > , this allows you to
interactively run commands in the same sort of shell environment that
< code > package.json< / code > scripts are run. Interactive mode is not supported in CI
environments when standard input is a TTY, to prevent hangs.< / p >
2020-11-03 20:39:24 -05:00
< p > Whatever packages are specified by the < code > --package< / code > option will be
2020-11-01 07:54:36 +01:00
provided in the < code > PATH< / code > of the executed command, along with any locally
2020-11-03 20:39:24 -05:00
installed package executables. The < code > --package< / code > option may be
2020-11-01 07:54:36 +01:00
specified multiple times, to execute the supplied command in an environment
where all specified packages are available.< / p >
< p > If any requested packages are not present in the local project
2022-12-06 22:18:33 -05:00
dependencies, then a prompt is printed, which can be suppressed by
providing either < code > --yes< / code > or < code > --no< / code > . When standard input is not a TTY or a
CI environment is detected, < code > --yes< / code > is assumed. The requested packages are
installed to a folder in the npm cache, which is added to the < code > PATH< / code >
environment variable in the executed process.< / p >
2020-11-01 07:54:36 +01:00
< p > Package names provided without a specifier will be matched with whatever
version exists in the local project. Package names with a specifier will
only be considered a match if they have the exact same name and version as
the local dependency.< / p >
< p > If no < code > -c< / code > or < code > --call< / code > option is provided, then the positional arguments
2020-11-03 20:39:24 -05:00
are used to generate the command string. If no < code > --package< / code > options
2020-11-01 07:54:36 +01:00
are provided, then npm will attempt to determine the executable name from
the package specifier provided as the first positional argument according
to the following heuristic:< / p >
< ul >
< li > If the package has a single entry in its < code > bin< / code > field in < code > package.json< / code > ,
2020-11-13 15:30:43 -05:00
or if all entries are aliases of the same command, then that command
will be used.< / li >
2020-11-01 07:54:36 +01:00
< li > If the package has multiple < code > bin< / code > entries, and one of them matches the
unscoped portion of the < code > name< / code > field, then that command will be used.< / li >
< li > If this does not result in exactly one option (either because there are
no bin entries, or none of them match the < code > name< / code > of the package), then
< code > npm exec< / code > exits with an error.< / li >
< / ul >
< p > To run a binary < em > other than< / em > the named binary, specify one or more
< code > --package< / code > options, which will prevent npm from inferring the package from
the first command argument.< / p >
< h3 id = "npx-vs-npm-exec" > < code > npx< / code > vs < code > npm exec< / code > < / h3 >
< p > When run via the < code > npx< / code > binary, all flags and options < em > must< / em > be set prior to
any positional arguments. When run via < code > npm exec< / code > , a double-hyphen < code > --< / code >
2021-11-18 20:58:02 +00:00
flag can be used to suppress npm's parsing of switches and options that
2020-11-01 07:54:36 +01:00
should be sent to the executed command.< / p >
< p > For example:< / p >
< pre > < code > $ npx foo@latest bar --package=@npmcli/foo
< / code > < / pre >
< p > In this case, npm will resolve the < code > foo< / code > package name, and run the
following command:< / p >
< pre > < code > $ foo bar --package=@npmcli/foo
< / code > < / pre >
< p > Since the < code > --package< / code > option comes < em > after< / em > the positional arguments, it is
treated as an argument to the executed command.< / p >
2021-11-18 20:58:02 +00:00
< p > In contrast, due to npm's argument parsing logic, running this command is
2020-11-01 07:54:36 +01:00
different:< / p >
< pre > < code > $ npm exec foo@latest bar --package=@npmcli/foo
< / code > < / pre >
< p > In this case, npm will parse the < code > --package< / code > option first, resolving the
< code > @npmcli/foo< / code > package. Then, it will execute the following command in that
context:< / p >
< pre > < code > $ foo@latest bar
< / code > < / pre >
< p > The double-hyphen character is recommended to explicitly tell npm to stop
parsing command line options and switches. The following command would
thus be equivalent to the < code > npx< / code > command above:< / p >
< pre > < code > $ npm exec -- foo@latest bar --package=@npmcli/foo
< / code > < / pre >
2021-05-20 15:54:50 -04:00
< h3 id = "configuration" > Configuration< / h3 >
< h4 id = "package" > < code > package< / code > < / h4 >
< ul >
< li > Default:< / li >
< li > Type: String (can be set multiple times)< / li >
< / ul >
2022-08-04 21:23:58 -07:00
< p > The package or packages to install for < a href = "../commands/npm-exec.html" > < code > npm exec< / code > < / a > < / p >
2021-05-20 15:54:50 -04:00
< h4 id = "call" > < code > call< / code > < / h4 >
< ul >
2021-11-18 20:58:02 +00:00
< li > Default: ""< / li >
2021-05-20 15:54:50 -04:00
< li > Type: String< / li >
< / ul >
< p > Optional companion option for < code > npm exec< / code > , < code > npx< / code > that allows for specifying a
custom command to be run along with the installed packages.< / p >
2022-12-06 22:18:33 -05:00
< pre > < code class = "language-bash" > npm exec --package yo --package generator-node --call "yo node"
2021-05-20 15:54:50 -04:00
< / code > < / pre >
< h4 id = "workspace" > < code > workspace< / code > < / h4 >
< ul >
< li > Default:< / li >
< li > Type: String (can be set multiple times)< / li >
< / ul >
< p > 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.< / p >
< p > Valid values for the < code > workspace< / code > config are either:< / p >
< ul >
< li > Workspace names< / li >
< li > Path to a workspace directory< / li >
2021-10-14 22:17:47 +00:00
< li > Path to a parent workspace directory (will result in selecting all
workspaces within that folder)< / li >
2021-05-20 15:54:50 -04:00
< / ul >
< p > When set for the < code > npm init< / code > 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.< / p >
< p > This value is not exported to the environment for child processes.< / p >
< h4 id = "workspaces" > < code > workspaces< / code > < / h4 >
< ul >
2021-10-14 22:17:47 +00:00
< li > Default: null< / li >
< li > Type: null or Boolean< / li >
2021-05-20 15:54:50 -04:00
< / ul >
2021-10-14 22:17:47 +00:00
< p > Set to true to run the command in the context of < strong > all< / strong > configured
2021-05-20 15:54:50 -04:00
workspaces.< / p >
2021-10-14 22:17:47 +00:00
< p > Explicitly setting this to false will cause commands like < code > install< / code > to
ignore workspaces altogether. When not set explicitly:< / p >
< ul >
< li > Commands that operate on the < code > node_modules< / code > tree (install, update, etc.)
will link workspaces into the < code > node_modules< / code > folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
< em > unless< / em > one or more workspaces are specified in the < code > workspace< / code > config.< / li >
< / ul >
2021-05-20 15:54:50 -04:00
< p > This value is not exported to the environment for child processes.< / p >
2021-10-14 22:17:47 +00:00
< h4 id = "include-workspace-root" > < code > include-workspace-root< / code > < / h4 >
< ul >
< li > Default: false< / li >
< li > Type: Boolean< / li >
< / ul >
< p > Include the workspace root when workspaces are enabled for a command.< / p >
< p > When false, specifying individual workspaces via the < code > workspace< / code > config, or
all workspaces via the < code > workspaces< / code > flag, will cause npm to operate only on
the specified workspaces, and not on the root project.< / p >
2022-04-14 21:57:02 +00:00
< p > This value is not exported to the environment for child processes.< / p >
2020-11-01 07:54:36 +01:00
< h3 id = "examples" > Examples< / h3 >
< p > Run the version of < code > tap< / code > in the local dependencies, with the provided
arguments:< / p >
< pre > < code > $ npm exec -- tap --bail test/foo.js
$ npx tap --bail test/foo.js
< / code > < / pre >
< p > Run a command < em > other than< / em > the command whose name matches the package name
by specifying a < code > --package< / code > option:< / p >
< pre > < code > $ npm exec --package=foo -- bar --bar-argument
# ~ or ~
$ npx --package=foo bar --bar-argument
< / code > < / pre >
< p > Run an arbitrary shell script, in the context of the current project:< / p >
< pre > < code > $ npm x -c 'eslint & & say "hooray, lint passed"'
$ npx -c 'eslint & & say "hooray, lint passed"'
< / code > < / pre >
2021-03-23 14:58:11 -04:00
< h3 id = "workspaces-support" > Workspaces support< / h3 >
2022-12-06 22:18:33 -05:00
< p > You may use the < a href = "../using-npm/config#workspace.html" > < code > workspace< / code > < / a > or
< a href = "../using-npm/config#workspaces.html" > < code > workspaces< / code > < / a > configs in order to run an
2021-03-23 14:58:11 -04:00
arbitrary command from an npm package (either one installed locally, or fetched
remotely) in the context of the specified workspaces.
If no positional argument or < code > --call< / code > option is provided, it will open an
interactive subshell in the context of each of these configured workspaces one
at a time.< / p >
< p > Given a project with configured workspaces, e.g:< / p >
< pre > < code > .
+-- package.json
`-- packages
+-- a
| `-- package.json
+-- b
| `-- package.json
`-- c
`-- package.json
< / code > < / pre >
< p > Assuming the workspace configuration is properly set up at the root level
< code > package.json< / code > file. e.g:< / p >
< pre > < code > {
"workspaces": [ "./packages/*" ]
}
< / code > < / pre >
< p > You can execute an arbitrary command from a package in the context of each of
2022-12-06 22:18:33 -05:00
the configured workspaces when using the
< a href = "../using-npm/config#workspace.html" > < code > workspaces< / code > config options< / a > , in this example
we're using < strong > eslint< / strong > to lint any js file found within each workspace folder:< / p >
2021-04-29 16:30:06 -04:00
< pre > < code > npm exec --ws -- eslint ./*.js
2021-03-23 14:58:11 -04:00
< / code > < / pre >
< h4 id = "filtering-workspaces" > Filtering workspaces< / h4 >
2021-11-18 20:58:02 +00:00
< p > It's also possible to execute a command in a single workspace using the
2021-03-23 14:58:11 -04:00
< code > workspace< / code > config along with a name or directory path:< / p >
< pre > < code > npm exec --workspace=a -- eslint ./*.js
< / code > < / pre >
< p > The < code > workspace< / code > config can also be specified multiple times in order to run a
specific script in the context of multiple workspaces. When defining values for
the < code > workspace< / code > config in the command line, it also possible to use < code > -w< / code > as a
shorthand, e.g:< / p >
< pre > < code > npm exec -w a -w b -- eslint ./*.js
< / code > < / pre >
< p > This last command will run the < code > eslint< / code > command in both < code > ./packages/a< / code > and
< code > ./packages/b< / code > folders.< / p >
2020-11-01 07:54:36 +01:00
< h3 id = "compatibility-with-older-npx-versions" > Compatibility with Older npx Versions< / h3 >
< p > The < code > npx< / code > binary was rewritten in npm v7.0.0, and the standalone < code > npx< / code >
package deprecated at that time. < code > npx< / code > uses the < code > npm exec< / code >
command instead of a separate argument parser and install process, with
some affordances to maintain backwards compatibility with the arguments it
accepted in previous versions.< / p >
< p > This resulted in some shifts in its functionality:< / p >
< ul >
< li > Any < code > npm< / code > config value may be provided.< / li >
< li > To prevent security and user-experience problems from mistyping package
names, < code > npx< / code > prompts before installing anything. Suppress this
prompt with the < code > -y< / code > or < code > --yes< / code > option.< / li >
< li > The < code > --no-install< / code > option is deprecated, and will be converted to < code > --no< / code > .< / li >
< li > Shell fallback functionality is removed, as it is not advisable.< / li >
< li > The < code > -p< / code > argument is a shorthand for < code > --parseable< / code > in npm, but shorthand
for < code > --package< / code > in npx. This is maintained, but only for the < code > npx< / code >
executable.< / li >
< li > The < code > --ignore-existing< / code > option is removed. Locally installed bins are
always present in the executed process < code > PATH< / code > .< / li >
< li > The < code > --npm< / code > option is removed. < code > npx< / code > will always use the < code > npm< / code > it ships
with.< / li >
< li > The < code > --node-arg< / code > and < code > -n< / code > options are removed.< / li >
< li > The < code > --always-spawn< / code > option is redundant, and thus removed.< / li >
< li > The < code > --shell< / code > option is replaced with < code > --script-shell< / code > , but maintained
in the < code > npx< / code > executable for backwards compatibility.< / li >
< / ul >
2021-01-28 17:38:39 -05:00
< h3 id = "a-note-on-caching" > A note on caching< / h3 >
< p > The npm cli utilizes its internal package cache when using the package
name specified. You can use the following to change how and when the
cli uses this cache. See < a href = "../commands/npm-cache.html" > < code > npm cache< / code > < / a > for more on
how the cache works.< / p >
< h4 id = "prefer-online" > prefer-online< / h4 >
< p > Forces staleness checks for packages, making the cli look for updates
immediately even if the package is already in the cache.< / p >
< h4 id = "prefer-offline" > prefer-offline< / h4 >
< p > Bypasses staleness checks for packages. Missing data will still be
requested from the server. To force full offline mode, use < code > offline< / code > .< / p >
< h4 id = "offline" > offline< / h4 >
< p > Forces full offline mode. Any packages not locally cached will result in
an error.< / p >
2021-05-20 15:54:50 -04:00
< h4 id = "workspace2" > workspace< / h4 >
2021-03-23 14:58:11 -04:00
< ul >
2021-05-20 15:54:50 -04:00
< li > Default:< / li >
< li > Type: String (can be set multiple times)< / li >
2021-03-23 14:58:11 -04:00
< / ul >
2021-05-20 15:54:50 -04:00
< p > 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.< / p >
2021-03-23 14:58:11 -04:00
< p > Valid values for the < code > workspace< / code > config are either:< / p >
< ul >
< li > Workspace names< / li >
< li > Path to a workspace directory< / li >
< li > Path to a parent workspace directory (will result to selecting all of the
2021-05-20 15:54:50 -04:00
nested workspaces)< / li >
2021-03-23 14:58:11 -04:00
< / ul >
2021-05-20 15:54:50 -04:00
< p > This value is not exported to the environment for child processes.< / p >
< h4 id = "workspaces2" > workspaces< / h4 >
2021-03-23 14:58:11 -04:00
< ul >
2021-04-29 16:30:06 -04:00
< li > Alias: < code > --ws< / code > < / li >
2021-03-23 14:58:11 -04:00
< li > Type: Boolean< / li >
< li > Default: < code > false< / code > < / li >
< / ul >
< p > Run scripts in the context of all configured workspaces for the current
project.< / p >
2020-11-01 07:54:36 +01:00
< h3 id = "see-also" > See Also< / h3 >
< ul >
< li > < a href = "../commands/npm-run-script.html" > npm run-script< / a > < / li >
< li > < a href = "../using-npm/scripts.html" > npm scripts< / a > < / li >
< li > < a href = "../commands/npm-test.html" > npm test< / a > < / li >
< li > < a href = "../commands/npm-start.html" > npm start< / a > < / li >
< li > < a href = "../commands/npm-restart.html" > npm restart< / a > < / li >
< li > < a href = "../commands/npm-stop.html" > npm stop< / a > < / li >
< li > < a href = "../commands/npm-config.html" > npm config< / a > < / li >
2021-04-29 16:30:06 -04:00
< li > < a href = "../using-npm/workspaces.html" > npm workspaces< / a > < / li >
2022-02-11 11:51:11 +02:00
< li > < a href = "../commands/npx.html" > npx< / a > < / li >
2022-12-06 22:18:33 -05:00
< / ul > < / div >
2020-11-01 07:54:36 +01:00
< footer id = "edit" >
< a href = "https://github.com/npm/cli/edit/latest/docs/content/commands/npm-exec.md" >
< svg role = "img" viewBox = "0 0 16 16" width = "16" height = "16" fill = "currentcolor" style = "vertical-align: text-bottom; margin-right: 0.3em;" >
< path fill-rule = "evenodd" d = "M11.013 1.427a1.75 1.75 0 012.474 0l1.086 1.086a1.75 1.75 0 010 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 01-.927-.928l.929-3.25a1.75 1.75 0 01.445-.758l8.61-8.61zm1.414 1.06a.25.25 0 00-.354 0L10.811 3.75l1.439 1.44 1.263-1.263a.25.25 0 000-.354l-1.086-1.086zM11.189 6.25L9.75 4.81l-6.286 6.287a.25.25 0 00-.064.108l-.558 1.953 1.953-.558a.249.249 0 00.108-.064l6.286-6.286z" > < / path >
< / svg >
Edit this page on GitHub
< / a >
< / footer >
< / section >
< / body > < / html >
