Node.js Process Lookup Utility

0.1.6 · abandoned · verified Sun Apr 19

ps-node is a Node.js module designed for looking up and managing running processes across different operating systems. It leverages native system commands like `ps` on Linux/macOS and `wmic` on Windows to retrieve detailed process information, including PID, command, and arguments. The package, currently at version 0.1.6, was last published nine years ago. Its primary functionality includes searching for processes by PID or filtering by command and arguments using regular expressions. Additionally, it offers a `kill` function to terminate processes, supporting optional signals and timeouts. Due to its age, it does not support modern Node.js features like ECMAScript Modules (ESM) and is likely incompatible with recent Node.js versions or major operating system updates. There is no ongoing release cadence, and it is largely superseded by more actively maintained alternatives.

Common errors

```
Error: spawn ps ENOENT
```
cause The `ps` command (or `wmic`/`cmd` on Windows) is not found in the system's PATH, or there are permission issues executing it.

fix Ensure that the `ps` command (on Linux/macOS) or `wmic` (on Windows) is installed and accessible in the system's PATH. Check execution permissions for the Node.js process. On Windows, ensure `cmd` is available.
```
Error: (some error message from underlying shell command output) -- parsing error
```
cause The output format of the underlying `ps` or `wmic` command has changed, or `table-parser` is unable to correctly parse the output, often due to unexpected characters or column shifts.

fix This package is not maintained, so direct fixes are unlikely. The best solution is to migrate to a more current process management library or implement custom parsing for the specific OS if `ps-node` is absolutely required.
```
Error: kill ESRCH
```
cause The process with the specified PID does not exist, or the Node.js process attempting to kill it does not have sufficient permissions.

fix Verify that the PID is correct and that the target process is still running. Ensure the Node.js application has the necessary permissions to send signals to other processes on the operating system.

Warnings

breaking The package is severely outdated (last updated 9 years ago) and may not function correctly on modern Node.js versions (e.g., Node.js v16+) or current operating systems due to changes in internal Node.js APIs or external command outputs.
Fix: Consider using more modern and actively maintained alternatives like `ps-list` or `systeminformation` for process management in Node.js.
gotcha The module relies on parsing the output of external shell commands (`ps` on *nix, `wmic` on Windows). Any changes to the output format or flags of these commands by the operating system could break `ps-node`'s functionality, leading to incorrect or missing process information.
Fix: Thoroughly test on all target operating systems and versions. For production-critical applications, consider implementing fallback mechanisms or using a more robust native solution if available.
gotcha The `kill` function wraps `process.kill()` and explicitly states that Node.js's built-in `process.kill()` does not accept numbers as signals, only strings (e.g., 'SIGKILL', 'SIGTERM'). Passing a numeric signal will result in an error or unexpected behavior.
Fix: Always use string representations for signals when calling `ps.kill()` (e.g., `ps.kill(pid, 'SIGKILL', callback)`).
deprecated The `command` and `arguments` options in `ps.lookup` for Windows environments might have limited functionality or miss full command arguments due to `wmic` limitations, or changes in how `tasklist` works (which is mentioned as an alternative but not directly used by default for arguments).
Fix: For Windows, carefully test the output accuracy of `command` and `arguments`. If precise command-line arguments are critical, `ps-node` might not be the most reliable solution, and a different library or direct `wmic`/`tasklist` invocation might be necessary. Note that some versions of `ps-node` (or forks) might concatenate command and arguments into a single string.

Install

npm install ps-node npm
yarn add ps-node yarn
pnpm add ps-node pnpm

Imports

ps
wrong:
```
const ps = require('ps-node');
```
correct:
```
import ps from 'ps-node';
```
The package was published before widespread ESM adoption. While `require` is shown in examples, modern Node.js applications using ESM should use `import ps from 'ps-node'` for CJS interoperability. Direct named ESM imports are not supported.

Quickstart

This quickstart demonstrates how to use `ps-node` to find running Node.js processes with specific debug arguments and then, as an example, attempts to terminate the first matching process.

const ps = require('ps-node');

// Look up processes matching a command and arguments
ps.lookup({
    command: 'node',
    arguments: '--debug'
}, function(err, resultList) {
    if (err) {
        console.error('Error looking up processes:', err);
        process.exit(1);
    }

    if (resultList.length === 0) {
        console.log('No matching processes found.');
        return;
    }

    console.log('Found matching processes:');
    resultList.forEach(function(process) {
        console.log('  PID: %s, COMMAND: %s, ARGUMENTS: %s', process.pid, process.command, process.arguments);
    });

    // Example: Kill the first found process after 5 seconds (for demonstration)
    if (resultList[0]) {
        const pidToKill = resultList[0].pid;
        console.log(`
Attempting to kill process ${pidToKill} in 5 seconds...`);
        setTimeout(() => {
            ps.kill(pidToKill, { signal: 'SIGTERM', timeout: 10 }, function(killErr) {
                if (killErr) {
                    console.error(`Error killing process ${pidToKill}:`, killErr);
                } else {
                    console.log(`Process ${pidToKill} has been killed!`);
                }
            });
        }, 5000);
    }
});

view raw JSON →