find process info by port/pid/name etc.
npm install find-process



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:
``sh`
$ npm install find-process -g
Usage:
`sh
Usage: find-process [options]
Options:
-V, --version output the version number
-t, --type
-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:
`sh`
$ npm install find-process --save
`typescript
import 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);`
});
`js
const find = require('find-process');
find('pid', 12345)
.then(function (list) {
console.log(list);
}, function (err) {
console.log(err.stack || err);
})
`
`typescript`
function find(type: 'port' | 'pid' | 'name', value: string | number, options?: FindConfig | boolean): Promise
- 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, .exe can 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):
`typescript`
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:
`typescript`
import { ProcessInfo, FindConfig, FindMethod } from 'find-process';
`typescript
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);`
}
});
`typescript
import find from 'find-process';
find('pid', 12345)
.then((list) => {
console.log(list);
})
.catch((err) => {
console.log(err.stack || err);
});
`
`typescript
import find from 'find-process';
find('name', 'nginx', true)
.then((list) => {
console.log(There are ${list.length} nginx process(es));`
});
`typescript
import find from 'find-process';
find('name', 'nginx', { strict: true, logLevel: 'error' })
.then((list) => {
console.log(Found ${list.length} nginx process(es));`
});
`typescript
import find from 'find-process';
async function findNodeProcesses() {
try {
const processes = await find('name', 'node');
console.log(Found ${processes.length} Node.js processes);PID: ${proc.pid}, Name: ${proc.name}, CMD: ${proc.cmd}
processes.forEach(proc => {
console.log();`
});
} catch (error) {
console.error('Error finding processes:', error);
}
}Development
- Node.js 16+
- pnpm (recommended) or npm
`bashClone the repository
git clone https://github.com/yibn2008/find-process.git
cd find-process
$3
-
pnpm run build - Compile TypeScript to JavaScript
- pnpm run dev - Watch mode for development
- pnpm test - Run tests
- pnpm run lint - Run linting and fix issues
- pnpm run type-check - TypeScript type checking
- pnpm run check-version - Verify version consistency
- pnpm run update-history - Update HISTORY.md with recent commitsContributing
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 build` completes successfully