Registry / devops / libnpmexec

libnpmexec

JSON →
library10.2.5jsnpmunverified

libnpmexec provides a programmatic interface to the core functionality of `npm exec` (and by extension, `npx`). It enables developers to execute packages and binaries found in the local `node_modules/.bin` directory, npm cache, or fetched from the npm registry, without directly invoking the `npm` CLI. The package is currently at version 10.2.5 and is actively maintained as part of the broader npm CLI monorepo, with a healthy release cadence. Its key differentiator is offering a low-level, configurable API to manage the lifecycle of package execution, including argument parsing, cache management, and user prompts, making it suitable for tooling and automation that requires direct control over script execution. It forms the underlying mechanism for the `npx` command line utility, handling package resolution and environment setup.

npm install libnpmexec
INSTALL
IMPORT
SIG · LIBNPMEXEC
L
libnpmexec
devopsjavascriptv10.2.5
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

libexec
import libexec from 'libnpmexec';
import { libexec } from 'libnpmexec';
The primary API is a default export function, often aliased as `libexec` by convention.
libexec (CJS)
const libexec = require('libnpmexec');
CommonJS usage for Node.js environments. The function is exported directly.

Demonstrates how to use `libnpmexec` to run a shell command and a package from the registry, including handling required options like `chalk`.

import libexec from 'libnpmexec'; import chalk from 'chalk'; const runCommand = async () => { try { console.log(chalk.blue('Attempting to execute `echo Hello libnpmexec!` using libnpmexec...')); // Execute a simple command, forcing confirmation if not explicitly suppressed // chalk instance is a required option const result = await libexec({ args: ['echo', 'Hello libnpmexec!'], yes: true, // Auto-confirm package installation if needed color: true, // Enable color output for commands that support it chalk: chalk, // You might also specify cache paths or run paths: // cache: process.env.NPM_CACHE_DIR ?? '~/.npm/_cacache', // npxCache: process.env.NPX_CACHE_DIR ?? '~/.npm/_npx', // path: process.cwd(), // Working directory // runPath: process.cwd(), // Directory to execute script in }); console.log(chalk.green('Command executed successfully:')); console.log(result.stdout || result.stderr); // libexec returns stdout/stderr in the result object // Example of executing a package that might need fetching (e.g., `cowsay`) console.log(chalk.yellow('\nAttempting to run `cowsay`...')); await libexec({ packages: ['cowsay'], args: ['Hello from a cow!'], yes: true, color: true, chalk: chalk, }); console.log(chalk.green('cowsay executed successfully.')); } catch (error) { console.error(chalk.red('Error executing command:'), error.message); process.exit(1); } }; runCommand();
Debug
Known issues
breakinglibnpmexec follows the npm CLI's major versioning, and upgrading across major versions (e.g., from v9 to v10) can introduce breaking changes. Always review the npm CLI changelog for corresponding `libnpmexec` updates, as direct breaking changes for its API might not be explicitly listed in its own dedicated changelog.
fix
Consult the main npm CLI changelog (github.com/npm/cli/releases) for migration guides related to the relevant `libnpmexec` version, paying close attention to API signature changes and option requirements.
affects: >=10.0.0
breakingThe `libexec` function requires a `chalk` instance to be passed in its options object for color output and interactive prompts. Failing to provide this will result in runtime errors.
fix
Ensure `chalk` is installed (`npm install chalk`) and pass a `chalk` instance to the `libexec` options, e.g., `await libexec({ ..., chalk: require('chalk') })`.
affects: >=1.0.0
gotchaThis package has strict Node.js engine requirements, currently `^20.17.0 || >=22.9.0`. Using an unsupported Node.js version will prevent the package from running and may lead to unexpected behavior or installation failures.
fix
Ensure your Node.js environment meets the specified engine requirements. Use a version manager like `nvm` to easily switch Node.js versions.
affects: >=1.0.0
gotchaWhen running commands in workspaces with `--package` and `--no-install` (or `--no`), older versions had a bug where the command would fail to execute even if the package was locally available. This could lead to 'npm ERR! canceled' or other terse errors.
fix
Upgrade `libnpmexec` to the latest stable version (10.x or newer) to leverage fixes for workspace-related execution logic. If upgrading is not immediately possible, consider omitting `--no-install` or explicitly managing package availability in the target workspace.
affects: <=9.0.4
Errors
Common errors & fixes
Error: Missing required option: chalk
The `chalk` instance was not provided in the options object to `libexec`.
fix
Install `chalk` (`npm install chalk`) and pass it as `chalk: require('chalk')` (CJS) or `chalk: chalk` (ESM, after `import chalk from 'chalk'`) in the `libexec` options.
TypeError: libexec is not a function
Incorrect import statement (e.g., using named import for a default export) or attempting to call a non-function.
fix
For CommonJS, use `const libexec = require('libnpmexec');`. For ES Modules, use `import libexec from 'libnpmexec';` to correctly import the default export function.
Unsupported Node.js version: Your current Node.js version (X.Y.Z) does not satisfy the required engine range of ^20.17.0 || >=22.9.0.
The Node.js version running the application is outside the range specified in the package's `engines` field.
fix
Upgrade or downgrade your Node.js environment to a compatible version, such as Node.js 20.17.0 or newer, or Node.js 22.9.0 or newer. Use `nvm` or `fnm` for easy Node.js version management.
Upgrade
Version history
10.2.5latest on npm
Audit
Dependencies
@npmcli/arboristrequiredUsed for dependency tree resolution and package installation/management logic, core to how libnpmexec identifies and prepares packages for execution.
Agent activity
2 hits · last 30 days
node
2
Resources