1---
2title: npx
3section: 1
4description: Run a command from a local or remote npm package
5---
6
7### Synopsis
8
9```bash
10npx -- <pkg>[@<version>] [args...]
11npx --package=<pkg>[@<version>] -- <cmd> [args...]
12npx -c '<cmd> [args...]'
13npx --package=foo -c '<cmd> [args...]'
14```
15
16### Description
17
18This command allows you to run an arbitrary command from an npm package
19(either one installed locally, or fetched remotely), in a similar context
20as running it via `npm run`.
21
22Whatever packages are specified by the `--package` option will be
23provided in the `PATH` of the executed command, along with any locally
24installed package executables.  The `--package` option may be
25specified multiple times, to execute the supplied command in an environment
26where all specified packages are available.
27
28If any requested packages are not present in the local project
29dependencies, then they are installed to a folder in the npm cache, which
30is added to the `PATH` environment variable in the executed process.  A
31prompt is printed (which can be suppressed by providing either `--yes` or
32`--no`).
33
34Package names provided without a specifier will be matched with whatever
35version exists in the local project.  Package names with a specifier will
36only be considered a match if they have the exact same name and version as
37the local dependency.
38
39If no `-c` or `--call` option is provided, then the positional arguments
40are used to generate the command string.  If no `--package` options
41are provided, then npm will attempt to determine the executable name from
42the package specifier provided as the first positional argument according
43to the following heuristic:
44
45- If the package has a single entry in its `bin` field in `package.json`,
46  or if all entries are aliases of the same command, then that command
47  will be used.
48- If the package has multiple `bin` entries, and one of them matches the
49  unscoped portion of the `name` field, then that command will be used.
50- If this does not result in exactly one option (either because there are
51  no bin entries, or none of them match the `name` of the package), then
52  `npm exec` exits with an error.
53
54To run a binary _other than_ the named binary, specify one or more
55`--package` options, which will prevent npm from inferring the package from
56the first command argument.
57
58### `npx` vs `npm exec`
59
60When run via the `npx` binary, all flags and options *must* be set prior to
61any positional arguments.  When run via `npm exec`, a double-hyphen `--`
62flag can be used to suppress npm's parsing of switches and options that
63should be sent to the executed command.
64
65For example:
66
67```
68$ npx foo@latest bar --package=@npmcli/foo
69```
70
71In this case, npm will resolve the `foo` package name, and run the
72following command:
73
74```
75$ foo bar --package=@npmcli/foo
76```
77
78Since the `--package` option comes _after_ the positional arguments, it is
79treated as an argument to the executed command.
80
81In contrast, due to npm's argument parsing logic, running this command is
82different:
83
84```
85$ npm exec foo@latest bar --package=@npmcli/foo
86```
87
88In this case, npm will parse the `--package` option first, resolving the
89`@npmcli/foo` package.  Then, it will execute the following command in that
90context:
91
92```
93$ foo@latest bar
94```
95
96The double-hyphen character is recommended to explicitly tell npm to stop
97parsing command line options and switches.  The following command would
98thus be equivalent to the `npx` command above:
99
100```
101$ npm exec -- foo@latest bar --package=@npmcli/foo
102```
103
104### Examples
105
106Run the version of `tap` in the local dependencies, with the provided
107arguments:
108
109```
110$ npm exec -- tap --bail test/foo.js
111$ npx tap --bail test/foo.js
112```
113
114Run a command _other than_ the command whose name matches the package name
115by specifying a `--package` option:
116
117```
118$ npm exec --package=foo -- bar --bar-argument
119# ~ or ~
120$ npx --package=foo bar --bar-argument
121```
122
123Run an arbitrary shell script, in the context of the current project:
124
125```
126$ npm x -c 'eslint && say "hooray, lint passed"'
127$ npx -c 'eslint && say "hooray, lint passed"'
128```
129
130### Compatibility with Older npx Versions
131
132The `npx` binary was rewritten in npm v7.0.0, and the standalone `npx`
133package deprecated at that time.  `npx` uses the `npm exec`
134command instead of a separate argument parser and install process, with
135some affordances to maintain backwards compatibility with the arguments it
136accepted in previous versions.
137
138This resulted in some shifts in its functionality:
139
140- Any `npm` config value may be provided.
141- To prevent security and user-experience problems from mistyping package
142  names, `npx` prompts before installing anything.  Suppress this
143  prompt with the `-y` or `--yes` option.
144- The `--no-install` option is deprecated, and will be converted to `--no`.
145- Shell fallback functionality is removed, as it is not advisable.
146- The `-p` argument is a shorthand for `--parseable` in npm, but shorthand
147  for `--package` in npx.  This is maintained, but only for the `npx`
148  executable.
149- The `--ignore-existing` option is removed.  Locally installed bins are
150  always present in the executed process `PATH`.
151- The `--npm` option is removed.  `npx` will always use the `npm` it ships
152  with.
153- The `--node-arg` and `-n` options have been removed. Use [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#node_optionsoptions) instead: e.g.,
154 `NODE_OPTIONS="--trace-warnings --trace-exit" npx foo --random=true`
155- The `--always-spawn` option is redundant, and thus removed.
156- The `--shell` option is replaced with `--script-shell`, but maintained
157  in the `npx` executable for backwards compatibility.
158
159### See Also
160
161* [npm run-script](/commands/npm-run-script)
162* [npm scripts](/using-npm/scripts)
163* [npm test](/commands/npm-test)
164* [npm start](/commands/npm-start)
165* [npm restart](/commands/npm-restart)
166* [npm stop](/commands/npm-stop)
167* [npm config](/commands/npm-config)
168* [npm exec](/commands/npm-exec)
169