npm-exec

Execute the command from a local or remote npm package

$ npm [[x|exec]] [command] [argument1 argument2 ...]

$ npm [[x|exec]] --package [package] [command]

$ npm [[x|exec]] --no-install [command] [argument1 argument2 ...]

$ npm [[x|exec]] --quiet [command] [argument1 argument2 ...]

$ npm [[x|exec]] --help

npm exec [options] [--] [<command-arg-list>]
npm exec [options] <pkg>[@<version>] [<command>] [--] [<command-arg-list>]
npx [options] [--] [<command-arg-list>] (alias)
npx [options] <pkg>[@<version>] [<command>] [--] [<command-arg-list>] (alias)

--
    
This is a crucial separator. Arguments following -- are passed directly to the executed command, preventing npm from interpreting them as its own options.

-c, --call <script-string>
    
Executes a string as a shell command. The string is interpreted as a Node.js script. This is similar to npm run, but executes commands from dependencies without needing a package.json script.

-p, --package <pkg>[@<version>]
    
Specifies a package (or multiple packages by repeating this option) that npm-exec should install before executing the command. If not specified, npm-exec infers the package name from the command itself.

--ignore-existing
    
Forces npm-exec to re-download and re-install the package even if it already exists in node_modules/.bin or the cache.

--no-install
    
Prevents npm-exec from installing packages if they are not found locally. If the command cannot be resolved from node_modules/.bin or PATH, it will fail.

-y, --yes
    
Automatically answers 'yes' to any prompts, such as confirming the installation of a package. Useful for non-interactive environments.

--shell <shell>
    
Specifies the shell to use for executing the command. By default, it uses the system's default shell (e.g., /bin/sh or cmd.exe).

--location <path>, --prefix <path>
    
Specifies where to install packages temporarily if needed. This can be useful for managing cache or installation locations.

npm-exec, often invoked via its alias npx, is a powerful utility for executing Node.js package binaries. Its primary purpose is to allow users to run commands provided by npm packages without needing to explicitly install those packages globally or locally first. When you execute a command using npm-exec, it first checks if the command exists in your local node_modules/.bin directory, and then in your system's PATH. If not found, it temporarily downloads and installs the necessary package(s) to a cache, runs the command, and then often removes the temporary installation. This makes it incredibly useful for one-off tasks, scaffolding new projects (e.g., create-react-app), trying out new tools without cluttering your global installations, or ensuring you're always running the latest version of a command without manual updates. Since npm@7, npm-exec is a core part of npm, with npx serving as a convenient alias.

Security Risk: Executing packages directly from npm can introduce security vulnerabilities if you're running untrusted code. Always be mindful of the source of the packages you execute.
Network Dependency: If the package is not found locally, npm-exec requires an active internet connection to download and install it.
Version Resolution: Without specifying a version (e.g., create-react-app@latest), npm-exec will use the latest available version, which might introduce breaking changes for repeated commands.
Temporary Installations: While convenient, be aware that packages are often installed temporarily and then removed, meaning subsequent executions might incur a download overhead.

The double-dash (--) separator is fundamental when using npm-exec (or npx) and passing arguments to the actual command being executed. Without it, npm might try to interpret those arguments as its own options, leading to unexpected behavior or errors. For example, to run some-command with the --help argument, you would use: npm exec some-command -- --help.

While npm-exec is the official command since npm@7, the npx command remains widely used. It functions as a direct alias for npm exec. So, npx create-react-app my-app is functionally identical to npm exec create-react-app my-app. This ensures that existing scripts and muscle memory continue to work seamlessly.

When you run a command via npm-exec, it follows a specific resolution order:
1. Checks if the command exists in the local node_modules/.bin directory of the current project.
2. Checks if the command exists in your system's PATH.
3. If not found, it determines the corresponding npm package, downloads it to a temporary cache, and then executes the binary from that temporary installation.
This intelligent lookup ensures efficiency and flexibility.

The concept of executing npm package binaries without prior installation was popularized by the standalone npx tool, first released in 2017. npx quickly became an essential part of the Node.js ecosystem, addressing a common pain point of managing global or local development dependencies. With the release of npm@7 in late 2020, the functionality of npx was integrated directly into the core npm CLI as npm-exec. Since then, npx continues to exist as a convenient alias that simply calls npm exec, ensuring backward compatibility while consolidating the toolchain.

npm(1), npm install(1), npm run(1), node(1)