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