npm-run-path 6.x

Complete instructions

Verified against npm-run-path@6.0.0 on 2026-09-08. 3 of 3 examples executed.

npm-run-path

npm-run-path 6.0.0 is an ESM package requiring Node.js 18 or newer. Import its two named exports:

import {npmRunPath, npmRunPathEnv} from 'npm-run-path';

It supplies PATH data; it is not a runner or CLI. Use the returned environment with Node's child_process APIs when launching a local binary outside an npm script.

API

npmRunPath(options?): string

Returns an augmented PATH string. Its options are:

• cwd?: string | URL — defaults to process.cwd().
• execPath?: string | URL — defaults to process.execPath.
• addExecPath?: boolean — defaults to true.
• preferLocal?: boolean — defaults to true.
• path?: string — the input PATH value; this option belongs to npmRunPath() only.

npmRunPathEnv(options?): ProcessEnv

Returns an augmented environment object based on process.env. Its options are:

• cwd?: string | URL — defaults to process.cwd().
• execPath?: string | URL — defaults to process.execPath.
• addExecPath?: boolean — defaults to true.
• preferLocal?: boolean — defaults to true.
• env?: ProcessEnv — the input environment; this option belongs to npmRunPathEnv() only.

ProcessEnv is Record<string, string | undefined>.

Examples

Construct a PATH and an environment

import assert from 'node:assert/strict';
import {npmRunPath, npmRunPathEnv} from 'npm-run-path';

const path = npmRunPath({
  path: '/usr/bin',
  preferLocal: false,
  addExecPath: false,
});

assert.equal(path, '/usr/bin');

const env = npmRunPathEnv({
  env: {
    PATH: '/usr/bin',
    CUSTOM_VALUE: 'kept',
  },
  preferLocal: false,
  addExecPath: false,
});

assert.equal(env.PATH, '/usr/bin');
assert.equal(env.CUSTOM_VALUE, 'kept');

Pass the generated environment to a child process

The package does not execute commands itself. Pass npmRunPathEnv() to a Node child-process API:

import assert from 'node:assert/strict';
import childProcess from 'node:child_process';
import {npmRunPathEnv} from 'npm-run-path';

const output = childProcess.execFileSync(
  process.execPath,
  ['-e', 'process.stdout.write(process.env.PMCP_VALUE ?? "")'],
  {
    env: npmRunPathEnv({
      env: {
        ...process.env,
        PMCP_VALUE: 'available-to-child',
      },
      preferLocal: false,
      addExecPath: false,
    }),
    encoding: 'utf8',
  },
);

assert.equal(output, 'available-to-child');

Use the options supported by the current type surface

cwd and execPath accept either strings or URLs. path is for npmRunPath; env is for npmRunPathEnv. Do not interchange those option names.

import assert from 'node:assert/strict';
import {npmRunPath, npmRunPathEnv} from 'npm-run-path';

const path = npmRunPath({
  cwd: new URL('.', import.meta.url),
  execPath: process.execPath,
  path: '/custom/path',
  preferLocal: false,
  addExecPath: false,
});
assert.equal(path, '/custom/path');

const environment = npmRunPathEnv({
  cwd: new URL('.', import.meta.url),
  execPath: process.execPath,
  env: {PATH: '/custom/path'},
  preferLocal: false,
  addExecPath: false,
});
assert.equal(environment.PATH, '/custom/path');

Common mistakes

• Using CommonJS imports: v6 is ESM ("type": "module"). Use named ESM imports from npm-run-path.
• Expecting the package to run a command: it only computes PATH data. Launch the command with Node's child_process APIs and provide env: npmRunPathEnv().
• Using the wrong input option: path is accepted by npmRunPath(), while env is accepted by npmRunPathEnv().
• Assuming the older major has a different API: the v5.3.0 examples use effectively the same two-function shape and option names. Code copied from that older documentation is still representative, but v6 requires Node.js 18 or newer.
• Forgetting the defaults: local npm binaries are preferred by default, the executable path is added by default, and the current working directory and process.execPath are used by default.
• Re-augmenting a PATH without considering v6 behavior: v6 makes the operation idempotent and handles an empty PATH better.

Not covered

This skill does not cover the internal directory-search algorithm, the exact ordering of every generated PATH segment, platform-specific PATH details, or the separate npm-run-path-cli package. It also does not cover runner-injected globals such as describe, it, or expect; examples here are standalone Bun scripts.