README.md
1[](https://npm.im/npx) [](https://npm.im/npx) [](https://travis-ci.org/npm/npx) [](https://ci.appveyor.com/project/npm/npx) [](https://coveralls.io/github/npm/npx?branch=latest)
2
3# npx(1) -- execute npm package binaries
4
5## SYNOPSIS
6
7`npx [options] <command>[@version] [command-arg]...`
8
9`npx [options] [-p|--package <pkg>]... <command> [command-arg]...`
10
11`npx [options] -c '<command-string>'`
12
13`npx --shell-auto-fallback [shell]`
14
15## INSTALL
16
17`npm install -g npx`
18
19## DESCRIPTION
20
21Executes `<command>` either from a local `node_modules/.bin`, or from a central cache, installing any packages needed in order for `<command>` to run.
22
23By default, `npx` will check whether `<command>` exists in `$PATH`, or in the local project binaries, and execute that. If `<command>` is not found, it will be installed prior to execution.
24
25Unless a `--package` option is specified, `npx` will try to guess the name of the binary to invoke depending on the specifier provided. All package specifiers understood by `npm` may be used with `npx`, including git specifiers, remote tarballs, local directories, or scoped packages.
26
27If a full specifier is included, or if `--package` is used, npx will always use a freshly-installed, temporary version of the package. This can also be forced with the `--ignore-existing` flag.
28
29* `-p, --package <package>` - define the package to be installed. This defaults to the value of `<command>`. This is only needed for packages with multiple binaries if you want to call one of the other executables, or where the binary name does not match the package name. If this option is provided `<command>` will be executed as-is, without interpreting `@version` if it's there. Multiple `--package` options may be provided, and all the packages specified will be installed.
30
31* `--no-install` - If passed to `npx`, it will only try to run `<command>` if it already exists in the current path or in `$prefix/node_modules/.bin`. It won't try to install missing commands.
32
33* `--cache <path>` - set the location of the npm cache. Defaults to npm's own cache settings.
34
35* `--userconfig <path>` - path to the user configuration file to pass to npm. Defaults to whatever npm's current default is.
36
37* `-c <string>` - Execute `<string>` inside an `npm run-script`-like shell environment, with all the usual environment variables available. Only the first item in `<string>` will be automatically used as `<command>`. Any others _must_ use `-p`.
38
39* `--shell <string>` - The shell to invoke the command with, if any.
40
41* `--shell-auto-fallback [<shell>]` - Generates shell code to override your shell's "command not found" handler with one that calls `npx`. Tries to figure out your shell, or you can pass its name (either `bash`, `fish`, or `zsh`) as an option. See below for how to install.
42
43* `--ignore-existing` - If this flag is set, npx will not look in `$PATH`, or in the current package's `node_modules/.bin` for an existing version before deciding whether to install. Binaries in those paths will still be available for execution, but will be shadowed by any packages requested by this install.
44
45* `-q, --quiet` - Suppressed any output from npx itself (progress bars, error messages, install reports). Subcommand output itself will not be silenced.
46
47* `-n, --node-arg` - Extra node argument to supply to node when binary is a node script. You can supply this option multiple times to add more arguments.
48
49* `-v, --version` - Show the current npx version.
50
51## EXAMPLES
52
53### Running a project-local bin
54
55```
56$ npm i -D webpack
57$ npx webpack ...
58```
59
60### One-off invocation without local installation
61
62```
63$ npm rm webpack
64$ npx webpack -- ...
65$ cat package.json
66...webpack not in "devDependencies"...
67```
68
69### Invoking a command from a github repository
70
71```
72$ npx github:piuccio/cowsay
73...or...
74$ npx git+ssh://my.hosted.git:cowsay.git#semver:^1
75...etc...
76```
77
78### Execute a full shell command using one npx call w/ multiple packages
79
80```
81$ npx -p lolcatjs -p cowsay -c \
82 'echo "$npm_package_name@$npm_package_version" | cowsay | lolcatjs'
83...
84 _____
85< your-cool-package@1.2.3 >
86 -----
87 \ ^__^
88 \ (oo)\_______
89 (__)\ )\/\
90 ||----w |
91 || ||
92```
93
94### Run node binary with --inspect
95
96```
97$ npx --node-arg=--inspect cowsay
98Debugger listening on ws://127.0.0.1:9229/....
99```
100
101### Specify a node version to run npm scripts (or anything else!)
102
103```
104npx -p node@8 npm run build
105```
106
107## SHELL AUTO FALLBACK
108
109You can configure `npx` to run as your default fallback command when you type something in the command line with an `@` but the command is not found. This includes installing packages that were not found in the local prefix either.
110
111For example:
112
113```
114$ npm@4 --version
115(stderr) npm@4 not found. Trying with npx...
1164.6.1
117$ asdfasdfasf
118zsh: command not found: asfdasdfasdf
119```
120
121Currently, `zsh`, `bash` (>= 4), and `fish` are supported. You can access these completion scripts using `npx --shell-auto-fallback <shell>`.
122
123To install permanently, add the relevant line below to your `~/.bashrc`, `~/.zshrc`, `~/.config/fish/config.fish`, or as needed. To install just for the shell session, simply run the line.
124
125You can optionally pass through `--no-install` when generating the fallback to prevent it from installing packages if the command is missing.
126
127### For bash@>=4:
128
129```
130$ source <(npx --shell-auto-fallback bash)
131```
132
133### For zsh:
134
135```
136$ source <(npx --shell-auto-fallback zsh)
137```
138
139### For fish:
140
141```
142$ source (npx --shell-auto-fallback fish | psub)
143```
144
145## ACKNOWLEDGEMENTS
146
147Huge thanks to [Kwyn Meagher](https://blog.kwyn.io) for generously donating the package name in the main npm registry. Previously `npx` was used for a Tessel board Neopixels library, which can now be found under [`npx-tessel`](https://npm.im/npx-tessel).
148
149## AUTHOR
150
151Written by [Kat Marchan](https://github.com/zkat).
152
153## REPORTING BUGS
154
155Please file any relevant issues [on Github.](https://github.com/npm/npx)
156
157## LICENSE
158
159This work is released by its authors into the public domain under CC0-1.0. See `LICENSE.md` for details.
160
161## SEE ALSO
162
163* `npm(1)`
164* `npm-run-script(1)`
165* `npm-config(7)`
166
){kind=link}
){kind=link}
){kind=link}
){kind=link}