{"record":{"id":"8338150a16527ee3","repo":"nodejs/node","slug":"the-programmatic-api-was-removed-in-npm-v8-0-0","errorCode":null,"errorMessage":"The programmatic API was removed in npm v8.0.0","messagePattern":"The programmatic API was removed in npm v8\\.0\\.0","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"deps/npm/index.js","lineNumber":4,"sourceCode":"if (require.main === module) {\n  require('./lib/cli.js')(process)\n} else {\n  throw new Error('The programmatic API was removed in npm v8.0.0')\n}\n","sourceCodeStart":1,"sourceCodeEnd":6,"githubUrl":"https://github.com/nodejs/node/blob/1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e/deps/npm/index.js#L1-L6","documentation":"npm v8+ removed its programmatic Node API. The entrypoint (deps/npm/index.js) only runs the CLI when invoked directly (require.main === module); requiring 'npm' from another module lands in the else branch and throws. The package is now CLI-only by design.","triggerScenarios":"Calling require('npm') or import 'npm' from a Node script, build tool, or test harness. Anything that loads the package without executing it as the main module hits the else branch.","commonSituations":"Migrating tooling off npm v7 or earlier that drove npm in-process; scripts that did require('npm')({ argv: [...] }) to run commands; plugins that imported npm to read its version or config.","solutions":["Spawn the CLI as a child process instead (e.g. execa('npm', ['install']) or child_process.spawn('npm', args, { stdio: 'inherit' }))","For dependency-tree work use @npmcli/arborist; for package fetching use pacote; for registry access use npm-registry-fetch; for config use @npmcli/config","If you only need npm's version, read require('npm/package.json').version (a static JSON file, not the entrypoint)","For exact legacy behavior, pin an older npm (v7) in a dedicated environment"],"exampleFix":"// before\nconst npm = require('npm')\nnpm.load(() => npm.commands.install(['lodash']))\n\n// after\nconst { spawn } = require('child_process')\nspawn('npm', ['install', 'lodash'], { stdio: 'inherit' })","handlingStrategy":"validation","validationCode":"// Detect before requiring: read the package metadata without invoking the entrypoint\nconst npmPkg = require('npm/package.json')\nconst major = Number(npmPkg.version.split('.')[0])\nif (major >= 8) {\n  throw new Error(`npm@${npmPkg.version} has no programmatic API; spawn the CLI instead`)\n}","typeGuard":"// Node has no static type for this; guard at runtime on the resolved package version\nfunction hasProgrammaticApi(npmVersion) {\n  const major = Number(String(npmVersion).split('.')[0])\n  return major < 8\n}","tryCatchPattern":null,"preventionTips":["Treat the npm package as CLI-only: always spawn `npm` rather than require()ing it","For in-process work, depend on the granular libraries (@npmcli/arborist, pacote, npm-registry-fetch, @npmcli/config)","Pin your tooling against a known npm major version in CI"],"tags":["npm","api","breaking-change","programmatic","require"],"backgroundTag":null,"analyzedSha":"1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e","analyzedAt":"2026-08-13T00:53:24.642Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}