What / Where

npx <command> / npm exec, when the command resolves to a bin declared by the local project itself (root package or a workspace — the "self-execution of a local bin" path in libnpmexec).

Current Behavior

The first time you npx <some-bin> from a package directory, npm installs that package into the npx cache (~/.npm/_npx/<hash>) as a directory spec and generates bin shims for the bins that exist at that moment. The cache key is derived solely from the package's absolute path:

// node_modules/npm/node_modules/libnpmexec/lib/index.js (npm 11.16.0), ~L242
const hash = crypto.createHash('sha512')
  .update(packages.map(p => {
    const spec = npa(p)
    if (spec.type === 'directory') return spec.fetchSpec // <- resolved absolute path
    return p
  }).sort((a, b) => a.localeCompare(b, 'en')).join('\n'))
  .digest('hex')
  .slice(0, 16)

Because the key is the path and nothing about the manifest's contents, every subsequent npx run for that directory reuses the same cache dir and never reinstalls. If you later add a new entry to the package's bin map, no shim is ever created for it, and:

$ npx --no-install my-new-bin
sh: my-new-bin: command not found

…even though my-new-bin is correctly declared in the local package.json and its source file exists. (The package folder in the cache is a symlink back to the project, so code edits are picked up live — only the bin list is frozen, because shims are generated once at install time.)

Steps To Reproduce

mkdir npx-stale-bin && cd npx-stale-bin
npm init -y

cat > a.js <<'EOF'
#!/usr/bin/env node
console.log('a')
EOF
cat > b.js <<'EOF'
#!/usr/bin/env node
console.log('b')
EOF

# declare ONE bin
npm pkg set bin.mytool-a=a.js

# first run — works, and creates the _npx cache for this directory
npx --no-install mytool-a          # -> "a"

# now add a SECOND bin to the same package
npm pkg set bin.mytool-b=b.js

# the new bin is declared in package.json, file exists...
npx --no-install mytool-b          # -> sh: mytool-b: command not found   (BUG)
node b.js                          # -> "b"  (proves the file is fine)

# proof it's the stale cache:
npm cache npx ls                   # shows the cached entry for this dir
npm cache npx rm --all
npx --no-install mytool-b          # -> "b"  (cache rebuilt with both bins)

Expected Behavior

When the resolved spec is a directory (a local/workspace package), npx should detect that the cached install is stale relative to the package's current bin map (or simply re-resolve bins for directory specs on every run) and create the missing shim — rather than silently reporting command not found for a bin the local package clearly declares.

Why this case specifically

The "reuse the cache, don't reinstall" logic is correct for every immutable spec type — pkg@1.2.3, a tarball URL, a git SHA all pin fixed contents, so keying by spec and never reinstalling is sound (and fast). The directory spec is the one case where a stable key maps to mutable contents: the directory's package.json (and its bin map) changes as the package is developed, but the key never does. The existing staleness fix (#8100) added auto-refresh only for semver range specs, leaving directory specs uncovered.

References

• Related: [BUG] npx does not fetch latest possible semvar match #7838, [BUG] npx not getting latest version, yes again! rfcs#700 (general npx cache staleness — closed)
• Prior fix that scoped auto-refresh to range specs only: add npm cache npx command and fix stale-version reuse in npx #8100

Environment

• npm: 11.16.0
• Node.js: 24.18.0
• Platform: macOS (Darwin 24.6.0)