npx: Usage, Options & Common CI Errors
npx runs a command from a local or remote npm package without installing it globally.
npx executes a package's binary on demand. In CI its hazards are the interactive "Ok to proceed?" prompt that hangs non-TTY jobs and silent version drift when nothing is pinned.
What it does
npx resolves a binary: it prefers a locally installed one (node_modules/.bin), otherwise downloads the package temporarily and runs it. Without a pinned version it fetches the latest, which is convenient but non-reproducible. --yes suppresses the install confirmation; --no-install forces use of an already-installed binary only.
Common usage
npx --yes prettier --check . # auto-confirm any download
npx prettier@3.3.2 --check . # pin the version (reproducible)
npx --no-install eslint . # fail if not already installed
npx create-vite@latest my-app -- --template reactCommon errors in CI
In a non-TTY job npx prompts "Need to install the following packages ... Ok to proceed? (y)" and hangs until timeout - pass --yes (or set CI=true, which many tools honor). "npm ERR! could not determine executable to run" means the package has no bin matching the name you invoked, or the name is misspelled. Unpinned npx tool@latest changes behavior run-to-run; pin the version. npx downloads on a cache miss, adding network flakiness - prefer a devDependency + npx --no-install for hot paths.
Options
| Flag | What it does |
|---|---|
| -y / --yes | Skip the install confirmation prompt |
| --no-install | Only use an already-installed binary |
| -p / --package <pkg> | Specify the package providing the bin |
| <pkg>@<version> | Pin the exact version (reproducible) |
Using this in CI
A runner shell is not a login shell. It does not read your dotfiles, it usually has no TTY, and by default it does not stop on the first error, so a failing command in the middle of a multi-line run block can leave the job green.
# make the shell behave the way you assume it does
- name: Build
shell: bash
run: |
set -euo pipefail # exit on error, undefined vars, and pipeline failures
./do-the-thing | tee out.log