{"id":13436,"library":"libnpmexec","title":"libnpmexec: Programmatic npm exec API","description":"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.","status":"active","version":"10.2.5","language":"javascript","source_language":"en","source_url":"https://github.com/npm/cli","tags":["javascript","npm","npmcli","libnpm","cli","workspaces","libnpmexec"],"install":[{"cmd":"npm install libnpmexec","lang":"bash","label":"npm"},{"cmd":"yarn add libnpmexec","lang":"bash","label":"yarn"},{"cmd":"pnpm add libnpmexec","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for dependency tree resolution and package installation/management logic, core to how libnpmexec identifies and prepares packages for execution.","package":"@npmcli/arborist","optional":false}],"imports":[{"note":"The primary API is a default export function, often aliased as `libexec` by convention.","wrong":"import { libexec } from 'libnpmexec';","symbol":"libexec","correct":"import libexec from 'libnpmexec';"},{"note":"CommonJS usage for Node.js environments. The function is exported directly.","symbol":"libexec (CJS)","correct":"const libexec = require('libnpmexec');"}],"quickstart":{"code":"import libexec from 'libnpmexec';\nimport chalk from 'chalk';\n\nconst runCommand = async () => {\n  try {\n    console.log(chalk.blue('Attempting to execute `echo Hello libnpmexec!` using libnpmexec...'));\n\n    // Execute a simple command, forcing confirmation if not explicitly suppressed\n    // chalk instance is a required option\n    const result = await libexec({\n      args: ['echo', 'Hello libnpmexec!'],\n      yes: true, // Auto-confirm package installation if needed\n      color: true, // Enable color output for commands that support it\n      chalk: chalk,\n      // You might also specify cache paths or run paths:\n      // cache: process.env.NPM_CACHE_DIR ?? '~/.npm/_cacache',\n      // npxCache: process.env.NPX_CACHE_DIR ?? '~/.npm/_npx',\n      // path: process.cwd(), // Working directory\n      // runPath: process.cwd(), // Directory to execute script in\n    });\n\n    console.log(chalk.green('Command executed successfully:'));\n    console.log(result.stdout || result.stderr); // libexec returns stdout/stderr in the result object\n\n    // Example of executing a package that might need fetching (e.g., `cowsay`)\n    console.log(chalk.yellow('\\nAttempting to run `cowsay`...'));\n    await libexec({\n      packages: ['cowsay'],\n      args: ['Hello from a cow!'],\n      yes: true,\n      color: true,\n      chalk: chalk,\n    });\n    console.log(chalk.green('cowsay executed successfully.'));\n\n  } catch (error) {\n    console.error(chalk.red('Error executing command:'), error.message);\n    process.exit(1);\n  }\n};\n\nrunCommand();","lang":"javascript","description":"Demonstrates how to use `libnpmexec` to run a shell command and a package from the registry, including handling required options like `chalk`."},"warnings":[{"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.","message":"libnpmexec 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.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Ensure `chalk` is installed (`npm install chalk`) and pass a `chalk` instance to the `libexec` options, e.g., `await libexec({ ..., chalk: require('chalk') })`.","message":"The `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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure your Node.js environment meets the specified engine requirements. Use a version manager like `nvm` to easily switch Node.js versions.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"<=9.0.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `chalk` instance was not provided in the options object to `libexec`.","error":"Error: Missing required option: chalk"},{"fix":"For CommonJS, use `const libexec = require('libnpmexec');`. For ES Modules, use `import libexec from 'libnpmexec';` to correctly import the default export function.","cause":"Incorrect import statement (e.g., using named import for a default export) or attempting to call a non-function.","error":"TypeError: libexec is not a function"},{"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.","cause":"The Node.js version running the application is outside the range specified in the package's `engines` field.","error":"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."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}