skip to content

With npm, what does `npx` do when the command's package is not installed in the project, and when does it ask before fetching it?

level: middleimportance: should knowfreq 18%

answer

  1. npx is npm exec underneath
  2. local copy first, then the registry
  3. a temporary folder in the npm cache
  4. the prompt, --yes and --no
  5. no TTY or CI means yes

basics

~20 s

npx (npm exec) runs a matching local copy; otherwise it installs the package into a folder in the npm cache and runs its bin. It prompts first, except with --yes or --no, or in CI or without a TTY, where yes is assumed.

solid answer

~50 s

Since npm 7, `npx` is `npm exec`. A bare name such as `npx @printroom/release-tool` matches whatever version the project already has; a name with a version matches a local copy only if the version is exactly the same. When nothing matches, npm resolves the package from the registry (a bare name gets the `latest` dist-tag by default), installs it into a folder in the npm cache — not into `node_modules`, not into `package.json` — adds it to the `PATH` of that one process and runs its `bin`. Before installing it prints a prompt: `--yes` (`-y`) accepts, `--no` refuses. When standard input is not a TTY or a CI environment is detected, `--yes` is assumed, so a CI job fetches silently. That is why a release step is safer as an npm script calling a declared devDependency than as a bare `npx` call.

go deeper

for a junior

Recall that npx runs a package's command, uses the project's installed copy when it has one, and otherwise asks before downloading it into the npm cache.

for a middle

Explain the matching rules for bare and versioned names, where fetched packages live, the --yes and --no answers, and that CI or a missing TTY means yes.

for a senior

Spot release and CI steps that depend on npx fetching latest, and move them to declared devDependencies run through npm scripts, or add --no so a missing tool fails loudly.

for a principal

Decide which tooling a team may run by name from the registry and which must be pinned in the lockfile, weighing convenience for one-off generators against reproducible release pipelines.

## What `npx` is in current npm The standalone `npx` package was deprecated when npm 7.0.0 rewrote `npx` on top of **`npm exec`**. Both run a command from an npm package — one installed locally or one fetched from the registry — in an environment like the one `npm run` prepares. The differences between them are about argument parsing, not about what gets fetched. ## How npx decides what to run For `npx @printroom/release-tool publish-notes`, npm works through these steps: 1. **Look locally.** A package name **without** a version is matched with whatever version the project already has installed. A name **with** a version, such as `@printroom/[email protected]`, counts as a match only if the local copy has exactly that name and version. 2. **Fetch if missing.** If nothing matches, npm resolves the name from the registry — a bare name resolves through the `tag` config, `latest` by default — and installs it into a **folder in the npm cache**. It does not touch the project's `node_modules`, `package.json` or lockfile. 3. **Choose the command.** If the package's `bin` field has a single entry, or one entry matching the unscoped part of its name, that command runs. Otherwise `npm exec` exits with an error, and you name the command explicitly with `--package`. 4. **Run it.** The fetched package's bin folder is added to the `PATH` of the executed process, alongside the project's own local bins, and the remaining arguments are passed to the command. ## The install prompt Before step 2 installs anything, npm prints a prompt asking whether to proceed. It exists because a mistyped name would otherwise fetch and run whatever package happens to carry that name. - `--yes` / `-y` answers yes in advance; - `--no` answers no, so a missing package is an error instead of a download; - `--no-install`, the old npx option, is deprecated and converted to `--no`; - when **standard input is not a TTY** or a **CI environment is detected**, npm assumes `--yes`. The last rule is what catches teams out. On a laptop, a teammate who has not run `npm install` sees a prompt for the release tool. In CI the same command proceeds without asking and runs whatever version the registry currently serves for that name. ## Pinning what npx runs | Command | What runs | |---|---| | `npx @printroom/release-tool` with the package installed | the project's installed version, no prompt | | the same command on a clone with no install | the registry's `latest`, after a prompt (silently in CI) | | `npx @printroom/[email protected]` with 3.2.0 installed | the local copy | | the same command with 3.1.0 installed | 3.2.0, fetched into the npm cache | | `npm run release`, where `release` calls the tool's bin | the version in the lockfile, or a "not found" error if it is missing | The last row is the robust option for a team: declare the tool as a devDependency, call it from an npm script, and `npm ci` decides the version. A bare `npx` call is fine for one-off generators and experiments. ## Argument parsing: `npx` against `npm exec` - With **`npx`**, every npm option must come **before** the first positional argument; anything after the package name goes to the command, so `npx tool --package=x` passes `--package=x` to `tool`. - With **`npm exec`**, npm parses options anywhere until a `--`; write `npm exec -- tool --flag` to hand everything after `--` to the command. - `-p` means `--package` only in the `npx` binary; in other npm commands `-p` is `--parseable`. - `-c` / `--call` runs a custom command string in the same environment. ## Traps - **A hidden version change.** The release tool worked yesterday because a teammate had it installed; today a fresh clone fetches a newer major from `latest`. - **Silent fetches in CI.** Because `--yes` is assumed there, add `--no` to a CI `npx` call that must only ever use the project's installed copy, so a missing devDependency fails loudly. - **Scoped names and several commands.** For `npx @printroom/release-tool`, when the package declares more than one `bin` entry, npm picks the one named `release-tool`, the unscoped part of the package name; if none matches, name the command with `--package`. - **A typo is a fetch.** The prompt is your one chance to notice that the name you typed is not the package you meant.

  • Does `npx` add the fetched package to `package.json` or the lockfile?
    No. A package `npx` has to fetch goes into a folder in the npm cache and is put on the `PATH` of that one process. The project's `node_modules`, `package.json` and `package-lock.json` are untouched, which is also why a later `npm ci` knows nothing about it.
  • Why does `npx tool --package=x` behave differently from `npm exec tool --package=x`?
    The `npx` binary stops reading npm options at the first positional argument, so `--package=x` goes to `tool`. `npm exec` keeps parsing npm options until it meets `--`, so it treats `--package=x` as its own option. Use `npm exec -- tool --package=x` to get the `npx` behaviour.

  • npx always downloads a fresh copy even when the package is installed
  • npx saves the fetched package into devDependencies
  • npx prompts in CI as well, so an unattended job will hang
  • npx [email protected] uses whatever version of tool is installed locally
  • The standalone npx package is still what the npx command runs