With find-process, you can:
- find the process which is listening specified port
- find the process by pid
- find the process by given name or name pattern
We have covered the difference of main OS platform, including macOS, Linux, Windows and Android (with Termux).
- âś… Full TypeScript Support - Written in TypeScript with complete type definitions
- âś… Cross-platform - Works on macOS, Linux, Windows, and Android
- âś… CLI Tool - Command-line interface for quick process lookup
- âś… Node.js API - Programmatic access with Promise-based API
- âś… Modern Build - ES2020 target with source maps and declaration files
Install find-process as a CLI tool:
$ npm install find-process -gUsage:
Usage: find-process [options] <keyword>
Options:
-V, --version output the version number
-t, --type <type> find process by keyword type (pid|port|name)
-p, --port find process by port
-h, --help output usage information
Examples:
$ find-process node # find by name "node"
$ find-process 111 # find by pid "111"
$ find-process -p 80 # find by port "80"
$ find-process -t port 80 # find by port "80"
Example:
You can use npm to install:
$ npm install find-process --saveimport find, { ProcessInfo, FindConfig } from "find-process";
// Find process by PID
find('pid', 12345)
.then((list: ProcessInfo[]) => {
console.log(list);
})
.catch((err: Error) => {
console.log(err.stack || err);
});
// With configuration options
const config: FindConfig = {
strict: true,
logLevel: 'warn'
};
find('name', 'nginx', config)
.then((list: ProcessInfo[]) => {
console.log(`Found ${list.length} nginx processes`);
});const find = require('find-process');
find('pid', 12345)
.then(function (list) {
console.log(list);
}, function (err) {
console.log(err.stack || err);
})function find(type: 'port' | 'pid' | 'name', value: string | number, options?: FindConfig | boolean): Promise<ProcessInfo[]>type- The type of search, supports:'port' | 'pid' | 'name'value- The value to search for. Can be RegExp if type is'name'options- Optional configuration object or boolean for strict modeoptions.strict- Optional strict mode for exact matching of port, pid, or name (on Windows,.execan be omitted)options.logLevel- Set logging level to'trace' | 'debug' | 'info' | 'warn' | 'error'. Useful for silencing netstat warnings on Linuxoptions.skipSelf- Skip the current process when searching by name
Returns a Promise that resolves to an array of process information ([] means no processes found):
interface ProcessInfo {
pid: number; // Process ID
ppid: number; // Parent process ID
uid?: number; // User ID (Unix systems)
gid?: number; // Group ID (Unix systems)
name: string; // Command/process name
bin?: string; // Executable path (Unix systems)
cmd: string; // Full command with arguments
}The package includes complete TypeScript definitions:
import { ProcessInfo, FindConfig, FindMethod } from 'find-process';import find from 'find-process';
find('port', 80)
.then((list) => {
if (!list.length) {
console.log('Port 80 is free now');
} else {
console.log(`${list[0].name} is listening on port 80`);
}
});import find from 'find-process';
find('pid', 12345)
.then((list) => {
console.log(list);
})
.catch((err) => {
console.log(err.stack || err);
});import find from 'find-process';
find('name', 'nginx', true)
.then((list) => {
console.log(`There are ${list.length} nginx process(es)`);
});import find from 'find-process';
find('name', 'nginx', { strict: true, logLevel: 'error' })
.then((list) => {
console.log(`Found ${list.length} nginx process(es)`);
});import find from 'find-process';
async function findNodeProcesses() {
try {
const processes = await find('name', 'node');
console.log(`Found ${processes.length} Node.js processes`);
processes.forEach(proc => {
console.log(`PID: ${proc.pid}, Name: ${proc.name}, CMD: ${proc.cmd}`);
});
} catch (error) {
console.error('Error finding processes:', error);
}
}- Node.js 16+
- pnpm (recommended) or npm
# Clone the repository
git clone https://github.com/yibn2008/find-process.git
cd find-process
# Install dependencies
pnpm install
# Build the project
pnpm run build
# Run tests
pnpm test
# Run linting
pnpm run lintpnpm run build- Compile TypeScript to JavaScriptpnpm run dev- Watch mode for developmentpnpm test- Run testspnpm run lint- Run linting and fix issuespnpm run type-check- TypeScript type checkingpnpm run check-version- Verify version consistencypnpm run update-history- Update HISTORY.md with recent commits
We welcome Pull Requests for bug fixes and new features. Please check the following before submitting a PR:
- Coding Style - Follow the Standard Style
- TypeScript - Ensure proper typing and no type errors
- Documentation - Add documentation for every API change
- Unit Tests - Add unit tests for bug fixes or new features
- Build - Ensure
pnpm run buildcompletes successfully