codekingpro/portable-devtools

1---
2title: npm-exec
3section: 1
4description: Run a command from a local or remote npm package
5---
6
7### Synopsis
8
9```bash
10npm exec -- <pkg>[@<version>] [args...]
11npm exec --package=<pkg>[@<version>] -- <cmd> [args...]
12npm exec -c '<cmd> [args...]'
13npm exec --package=foo -c '<cmd> [args...]'
14
15alias: x
16```
17
18### Description
19
20This 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 `npm run`.
21
22Run without positional arguments or `--call`, this allows you to interactively run commands in the same sort of shell environment that `package.json` scripts are run.
23Interactive mode is not supported in CI environments when standard input is a TTY, to prevent hangs.
24
25Whatever packages are specified by the `--package` option will be provided in the `PATH` of the executed command, along with any locally installed package executables.
26The `--package` option may be specified multiple times, to execute the supplied command in an environment where all specified packages are available.
27
28If any requested packages are not present in the local project dependencies, then a prompt is printed, which can be suppressed by providing either `--yes` or `--no`.
29When standard input is not a TTY or a CI environment is detected, `--yes` is assumed.
30The requested packages are installed to a folder in the npm cache, which is added to the `PATH` environment variable in the executed process.
31
32Package names provided without a specifier will be matched with whatever version exists in the local project.
33Package names with a specifier will only be considered a match if they have the exact same name and version as the local dependency.
34
35If no `-c` or `--call` option is provided, then the positional arguments are used to generate the command string.
36If no `--package` options 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:
37
38- If the package has a single entry in its `bin` field in `package.json`, or if all entries are aliases of the same command, then that command will be used.
39- If the package has multiple `bin` entries, and one of them matches the unscoped portion of the `name` field, then that command will be used.
40- If this does not result in exactly one option (either because there are no bin entries, or none of them match the `name` of the package), then `npm exec` exits with an error.
41
42To run a binary _other than_ the named binary, specify one or more `--package` options, which will prevent npm from inferring the package from the first command argument.
43
44### `npx` vs `npm exec`
45
46When run via the `npx` binary, all flags and options *must* be set prior to any positional arguments.
47When run via `npm exec`, a double-hyphen `--` flag can be used to suppress npm's parsing of switches and options that should be sent to the executed command.
48
49For example:
50
51```
52$ npx foo@latest bar --package=@npmcli/foo
53```
54
55In this case, npm will resolve the `foo` package name, and run the following command:
56
57```
58$ foo bar --package=@npmcli/foo
59```
60
61Since the `--package` option comes _after_ the positional arguments, it is treated as an argument to the executed command.
62
63In contrast, due to npm's argument parsing logic, running this command is different:
64
65```
66$ npm exec foo@latest bar --package=@npmcli/foo
67```
68
69In this case, npm will parse the `--package` option first, resolving the `@npmcli/foo` package.
70Then, it will execute the following command in that context:
71
72```
73$ foo@latest bar
74```
75
76The double-hyphen character is recommended to explicitly tell npm to stop parsing command line options and switches.
77The following command would thus be equivalent to the `npx` command above:
78
79```
80$ npm exec -- foo@latest bar --package=@npmcli/foo
81```
82
83### Configuration
84
85#### `package`
86
87* Default:
88* Type: String (can be set multiple times)
89
90The package or packages to install for [`npm exec`](/commands/npm-exec)
91
92
93
94#### `call`
95
96* Default: ""
97* Type: String
98
99Optional companion option for `npm exec`, `npx` that allows for specifying a
100custom command to be run along with the installed packages.
101
102```bash
103npm exec --package yo --package generator-node --call "yo node"
104```
105
106
107
108#### `workspace`
109
110* Default:
111* Type: String (can be set multiple times)
112
113Enable running a command in the context of the configured workspaces of the
114current project while filtering by running only the workspaces defined by
115this configuration option.
116
117Valid values for the `workspace` config are either:
118
119* Workspace names
120* Path to a workspace directory
121* Path to a parent workspace directory (will result in selecting all
122  workspaces within that folder)
123
124When set for the `npm init` command, this may be set to the folder of a
125workspace which does not yet exist, to create the folder and set it up as a
126brand new workspace within the project.
127
128This value is not exported to the environment for child processes.
129
130#### `workspaces`
131
132* Default: null
133* Type: null or Boolean
134
135Set to true to run the command in the context of **all** configured
136workspaces.
137
138Explicitly setting this to false will cause commands like `install` to
139ignore workspaces altogether. When not set explicitly:
140
141- Commands that operate on the `node_modules` tree (install, update, etc.)
142will link workspaces into the `node_modules` folder. - Commands that do
143other things (test, exec, publish, etc.) will operate on the root project,
144_unless_ one or more workspaces are specified in the `workspace` config.
145
146This value is not exported to the environment for child processes.
147
148#### `include-workspace-root`
149
150* Default: false
151* Type: Boolean
152
153Include the workspace root when workspaces are enabled for a command.
154
155When false, specifying individual workspaces via the `workspace` config, or
156all workspaces via the `workspaces` flag, will cause npm to operate only on
157the specified workspaces, and not on the root project.
158
159This value is not exported to the environment for child processes.
160
161### Examples
162
163Run the version of `tap` in the local dependencies, with the provided arguments:
164
165```
166$ npm exec -- tap --bail test/foo.js
167$ npx tap --bail test/foo.js
168```
169
170Run a command _other than_ the command whose name matches the package name by specifying a `--package` option:
171
172```
173$ npm exec --package=foo -- bar --bar-argument
174# ~ or ~
175$ npx --package=foo bar --bar-argument
176```
177
178Run an arbitrary shell script, in the context of the current project:
179
180```
181$ npm x -c 'eslint && say "hooray, lint passed"'
182$ npx -c 'eslint && say "hooray, lint passed"'
183```
184
185### Workspaces support
186
187You may use the [`workspace`](/using-npm/config#workspace) or [`workspaces`](/using-npm/config#workspaces) configs in order to run an arbitrary command from an npm package (either one installed locally, or fetched remotely) in the context of the specified workspaces.
188If no positional argument or `--call` option is provided, it will open an interactive subshell in the context of each of these configured workspaces one at a time.
189
190Given a project with configured workspaces, e.g:
191
192```
193.
194+-- package.json
195`-- packages
196   +-- a
197   |   `-- package.json
198   +-- b
199   |   `-- package.json
200   `-- c
201       `-- package.json
202```
203
204Assuming the workspace configuration is properly set up at the root level `package.json` file.
205e.g:
206
207```
208{
209    "workspaces": [ "./packages/*" ]
210}
211```
212
213You can execute an arbitrary command from a package in the context of each of the configured workspaces when using the [`workspaces` config options](/using-npm/config#workspace), in this example we're using **eslint** to lint any js file found within each workspace folder:
214
215```
216npm exec --ws -- eslint ./*.js
217```
218
219#### Filtering workspaces
220
221It's also possible to execute a command in a single workspace using the `workspace` config along with a name or directory path:
222
223```
224npm exec --workspace=a -- eslint ./*.js
225```
226
227The `workspace` config can also be specified multiple times in order to run a specific script in the context of multiple workspaces.
228When defining values for the `workspace` config in the command line, it also possible to use `-w` as a shorthand, e.g:
229
230```
231npm exec -w a -w b -- eslint ./*.js
232```
233
234This last command will run the `eslint` command in both `./packages/a` and
235`./packages/b` folders.
236
237### Compatibility with Older npx Versions
238
239The `npx` binary was rewritten in npm v7.0.0, and the standalone `npx` package deprecated at that time.
240`npx` uses the `npm exec` 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.
241
242This resulted in some shifts in its functionality:
243
244- Any `npm` config value may be provided.
245- To prevent security and user-experience problems from mistyping package
246  names, `npx` prompts before installing anything.
247  Suppress this prompt with the `-y` or `--yes` option.
248- The `--no-install` option is deprecated, and will be converted to `--no`.
249- Shell fallback functionality is removed, as it is not advisable.
250- The `-p` argument is a shorthand for `--parseable` in npm, but shorthand for `--package` in npx.
251  This is maintained, but only for the `npx` executable.
252- The `--ignore-existing` option is removed.
253  Locally installed bins are always present in the executed process `PATH`.
254- The `--npm` option is removed.
255  `npx` will always use the `npm` it ships with.
256- The `--node-arg` and `-n` options are removed.
257- The `--always-spawn` option is redundant, and thus removed.
258- The `--shell` option is replaced with `--script-shell`, but maintained in the `npx` executable for backwards compatibility.
259
260### A note on caching
261
262The npm cli utilizes its internal package cache when using the package name specified.
263You can use the following to change how and when the cli uses this cache.
264See [`npm cache`](/commands/npm-cache) for more on how the cache works.
265
266#### prefer-online
267
268Forces staleness checks for packages, making the cli look for updates immediately even if the package is already in the cache.
269
270#### prefer-offline
271
272Bypasses staleness checks for packages.
273Missing data will still be requested from the server.
274To force full offline mode, use `offline`.
275
276#### offline
277
278Forces full offline mode.
279Any packages not locally cached will result in an error.
280
281#### workspace
282
283* Default:
284* Type: String (can be set multiple times)
285
286Enable 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.
287
288Valid values for the `workspace` config are either:
289
290* Workspace names
291* Path to a workspace directory
292* Path to a parent workspace directory (will result to selecting all of the nested workspaces)
293
294This value is not exported to the environment for child processes.
295
296#### workspaces
297
298* Alias: `--ws`
299* Type: Boolean
300* Default: `false`
301
302Run scripts in the context of all configured workspaces for the current project.
303
304### See Also
305
306* [npm run](/commands/npm-run)
307* [npm scripts](/using-npm/scripts)
308* [npm test](/commands/npm-test)
309* [npm start](/commands/npm-start)
310* [npm restart](/commands/npm-restart)
311* [npm stop](/commands/npm-stop)
312* [npm config](/commands/npm-config)
313* [npm workspaces](/using-npm/workspaces)
314* [npx](/commands/npx)
315