What is npx

npx is a new command line interface (CLI) tool that allows you to download a package locally and run it in the current working directory. Let's see how to use it and which parameters it accepts.

Arguments

To install and run an npm package, you first need to locate the package's name in the npm registry. For example, in order to develop a new React application we need to initialize our project first. We can use the create-react-app package to solve this task. So to run this application locally without installing it we need to run the following command:

npx create-react-app my-app

This command will download all the necessary files to run the package create-react-app and execute it with provided parameter my-app. So, our application is created and initialized in the folder my-app.

In case we need to download some specific version, we can mention it after the @ sign, like this:

npx [email protected] my-app

Package resolution

npx will try to resolve locally installed packages first, and then will download and cache dependency to the special place, which can be found with the npm config get cache command. Inside this folder there is a special folder called _npx.

In order to resolve which script should be run, npx uses the following resolution algorithm:

1. Try to resolve the first provided parameter as package name:

   • If found locally then go to step 3

   • If not found locally ask to install

   • If the user allows downloading the package, then download it

2. If package.json has single bin entry, then execute it

3. If package.json has multiple bin entries and one of them matches package name, then execute it

4. Otherwise npx will fail to start

Command parameters

npx allows you to download several packages with different names. For example, if the package name doesn't match the executable name, then we can use the --package or -p key to set the package name we need to download. We can even download several packages:

npx -p cowsay -p lolcatjs cowsay hello

But to be able to run several packages in one environment we have to use another parameter, --call or -c. With it, we can run arbitrary commands inside a common environment. For example, let's run cowsay and pass the output to lolcatjs. To do this we have to use the -c parameter:

npx -p cowsay -p lolcatjs -c "cowsay hello | lolcatjs"

Then our output becomes colored.

Differences between npx and npm exec

npx and npm exec are synonyms in the world of NPM. The only difference between them is how they operate with flags and switches. For example, for npx all flags and options must be set prior to any positional arguments.

For example:

npx cowsay hello -p cowsay -p lolcatjs

This command will be treated as:

cowsay hello -p cowsay -p lolcatjs

And the parameters will be passed to the command cowsay.

And if we run the same command with npm exec

npm exec cowsay hello -p cowsay -p lolcatjs

It would be interpreted like the following:

cowsay hello

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 npx command above:

npm exec -- cowsay hello -p cowsay -p lolcatjs

Easter egg

npx has one secret undocumented feature: it can execute arbitrary scripts from GitHub Gists.

npx https://gist.github.com/zkat/4bc19503fe9e9309e2bfaa2c58074d32

Conclusion

npx is a great tool to use if you have to run some runnable package from NPM. It will help you run locally installed packages as well as remote packages you don't want to install or needed just for some rare cases or just for fun. A full list of commands and usages can be found in the official documentation. You can find some examples of useful npx commands here.