portclear

Enterprise-grade port management utility for modern development workflows
Zero dependencies • Cross-platform • Universal language support • Production-ready

Overview

portclear is a lightweight, zero-dependency utility designed to terminate processes occupying specified network ports. Built for modern development workflows, it supports all major operating systems and programming languages, making it an essential tool for developers, DevOps engineers, and system administrators.

Key Highlights

Feature	Description
Zero Dependencies	Pure Node.js implementation using only built-in modules
Cross-Platform	Windows, macOS, Linux, and Unix systems fully supported
Language Agnostic	Works with processes from any programming language
Port Ranges	Kill multiple ports simultaneously with range syntax
Preview Mode	Inspect processes before termination
TypeScript Native	Full type definitions included out of the box
Production Ready	Battle-tested with comprehensive error handling
Minimal Footprint	~10 KB package size vs 60-174 KB in alternatives

Why portclear?

Technical Advantages

┌─────────────────────────────────────────────────────────────────┐
│  COMPARISON: portclear vs Alternatives                          │
├─────────────────┬───────────┬───────────┬───────────┬───────────┤
│ Metric          │ portclear │ kill-port │  killport │ port-kill │
├─────────────────┼───────────┼───────────┼───────────┼───────────┤
│ Package Size    │   ~10 KB  │  ~60 KB   │  ~1.5 KB  │  ~35 KB   │
│ Dependencies    │     0     │     2     │     2     │     0     │
│ TypeScript      │     ✓     │  @types   │     ✗     │     ✗     │
│ Port Ranges     │     ✓     │     ✗     │     ✗     │     ✗     │
│ Preview Mode    │     ✓     │     ✗     │     ✗     │     ✓     │
│ JSON Output     │     ✓     │     ✗     │     ✗     │     ✗     │
│ Process Tree    │     ✓     │     ✗     │     ✗     │     ✓     │
│ Windows Support │     ✓     │     ✓     │     ✗     │     ✓     │
│ Quiet Mode      │     ✓     │     ✗     │     ✗     │     ✗     │
│ Active / Latest │     ✓     │     ✗     │     ✗     │     ✗     │
└─────────────────┴───────────┴───────────┴───────────┴───────────┘

Design Philosophy

Simplicity First: Single-purpose tool that does one thing exceptionally well
Developer Experience: Intuitive CLI with comprehensive documentation
Zero Lock-in: No proprietary dependencies or vendor tie-ins
Enterprise Grade: Production-ready with robust error handling
Future Proof: Active maintenance and continuous improvements

Installation

Quick Install (Recommended)

Use npx for one-time execution without global installation:

npx portclear 3000

Global Installation

Install once, use everywhere:

npm install -g portclear

Project Dependency

Add to your project's development dependencies:

npm install --save-dev portclear

yarn add -D portclear

pnpm add -D portclear

Available Package Aliases

For convenience, portclear is published under multiple package names:

Package Name	Command	Status
portclear	`npx portclear`	Primary (recommended)
portstop	`npx portstop`	Alias
pkill-port	`npx pkill-port`	Alias
port-nuke	`npx port-nuke`	Alias
port-eject	`npx port-eject`	Alias

Note: All aliases provide identical functionality. Use whichever name you prefer.

Quick Start

Basic Usage

# Kill process on port 3000
npx portclear 3000

# Kill multiple ports
npx portclear 3000 8080 9000

# Kill port range
npx portclear 3000-3010

# Preview without killing
npx portclear --list 3000

Common Scenarios

Before Starting Development Server

# Clean up before npm start
npx portclear 3000
npm start

CI/CD Pipeline

# Silent cleanup in scripts
npx portclear --quiet 3000 || true

Docker Port Conflicts

# Free up Docker ports
npx portclear 2375 2376 5000

Multiple Microservices

# Clear service port range
npx portclear 8000-8010

CLI Reference

Command Syntax

portclear [options] <port|range|ports...>

Options

Option	Short	Type	Description
`--port <port>`	`-p`	number	Specify port number (supports ranges and comma-separated lists)
`--list`	`-l`	boolean	List processes without terminating (preview mode)
`--method <protocol>`	`-m`	string	Protocol type: `tcp` or `udp` (default: `tcp`)
`--verbose`	`-v`	boolean	Display detailed output including PIDs and process names
`--quiet`	`-q`	boolean	Suppress output (errors only)
`--json`		boolean	Output results in JSON format
`--tree`		boolean	Terminate process tree including child processes
`--from <port>`		number	Start of port range
`--to <port>`		number	End of port range
`--help`	`-h`	boolean	Display help information

Usage Examples

Port Range Operations

# Range syntax (dash notation)
portclear 3000-3010

# Range syntax (flags)
portclear --from 3000 --to 3010

# Mixed ranges and individual ports
portclear 3000-3005 8080 9000

# Comma-separated ports
portclear -p 3000,8080,9000

Preview Mode (List Without Killing)

# Basic listing
portclear --list 3000

# Verbose listing with process details
portclear -l 3000 -v

# List port range
portclear --list 3000-3010

# JSON output for automation
portclear -l --json 3000

Protocol-Specific Operations

# Kill TCP process (default)
portclear 3000

# Kill UDP process
portclear -p 5353 -m udp

# Kill both TCP and UDP
portclear -p 53 -m tcp && portclear -p 53 -m udp

Process Tree Termination

# Kill parent and all child processes
portclear --tree 3000

# Useful for processes that spawn workers
portclear --tree 8000 -v

Automation & Scripting

# Quiet mode for CI/CD
portclear --quiet 3000

# JSON output for parsing
portclear --json 3000 | jq '.ports[0].killed'

# Conditional execution
if portclear -q 3000; then
  echo "Port cleared successfully"
else
  echo "Failed to clear port"
  exit 1
fi

API Documentation

JavaScript/TypeScript API

portclear provides a clean, promise-based API for programmatic usage.

Basic Usage

const portclear = require('portclear');

// Kill process on port 3000
await portclear(3000);

Advanced Options

// Configure with options object
await portclear(3000, {
  method: 'tcp',    // 'tcp' | 'udp'
  list: false,      // Preview mode
  tree: true        // Kill process tree
});

// Backward compatible (v0.x syntax still supported)
await portclear(3000, 'udp');

TypeScript Support

import portclear, { PortClearOptions, PortClearResult } from 'portclear';

// Type-safe configuration
const options: PortClearOptions = {
  method: 'tcp',
  list: true,
  tree: false
};

// Type-safe result handling
const result: PortClearResult = await portclear(3000, options);

if (result.killed) {
  console.log(`Terminated ${result.name} (PID: ${result.pid})`);
}

Type Definitions

interface PortClearOptions {
  method?: 'tcp' | 'udp';  // Protocol type
  list?: boolean;           // Preview mode
  tree?: boolean;           // Kill process tree
}

interface PortClearResult {
  port: number;            // Port number
  killed: boolean;         // Termination status
  platform: string;        // Operating system
  pid?: number;            // Primary process ID
  pids?: number[];         // All process IDs
  name?: string;           // Process name
  error?: string;          // Error message if failed
  stdout?: string;         // Command output
  stderr?: string;         // Command errors
  listing?: boolean;       // Preview mode indicator
}

Error Handling

try {
  const result = await portclear(3000);
  console.log(`Successfully terminated process on port ${result.port}`);
} catch (error) {
  if (error.message.includes('Permission denied')) {
    console.error('Insufficient privileges. Try running with sudo.');
  } else if (error.message.includes('No process running')) {
    console.log('Port is already available.');
  } else {
    console.error(`Unexpected error: ${error.message}`);
  }
}

Preview Before Termination

// Safe operation: preview then terminate
async function safeKill(port) {
  // Step 1: List process
  const preview = await portclear(port, { list: true });
  
  if (preview.error) {
    console.log(`Port ${port} is free`);
    return;
  }
  
  console.log(`Found: ${preview.name} (PID: ${preview.pid})`);
  
  // Step 2: Confirm with user (in interactive mode)
  const confirmed = await getUserConfirmation();
  
  // Step 3: Terminate if confirmed
  if (confirmed) {
    await portclear(port);
    console.log('Process terminated successfully');
  }
}

Universal Language Support

portclear operates at the operating system level, making it language-agnostic. It works with processes from any programming language or runtime.

Supported Languages & Frameworks

Language	Frameworks & Runtimes	Default Ports
JavaScript/TypeScript	Node.js, Deno, Bun, Express, Next.js, React, Vue, Angular dev servers	3000, 3001, 8080
Python	Flask, Django, FastAPI, Streamlit, Jupyter notebooks	5000, 8000, 8888
Go	Gin, Echo, Fiber, net/http	8080, 8000
Java/Kotlin	Spring Boot, Micronaut, Ktor, Tomcat, Jetty	8080, 8081, 9090
Ruby	Rails, Sinatra, Puma, Rack	3000, 4000
PHP	Laravel, Symfony, built-in server	8000, 8080
Rust	Actix, Rocket, Axum, Warp	8000, 3000
C/C++	Any HTTP server, TCP/UDP services	Varies
.NET/C#	ASP.NET Core, Kestrel	5000, 5001
Elixir	Phoenix	4000

How It Works

portclear doesn't interact with your application code. Instead, it:

Queries the operating system for processes using the specified port
Identifies the process ID (PID) via platform-specific commands:
- Windows: netstat -ano + taskkill
- Unix/Linux/macOS: lsof -ti + kill
Terminates the process using OS-level signals

This approach ensures compatibility with any language or framework that uses network ports.

Advanced Usage

Integration Patterns

Express.js Application

const portclear = require('portclear');
const express = require('express');

async function createServer(port = 3000) {
  try {
    // Clean port before starting
    await portclear(port, { quiet: true });
    
    const app = express();
    
    // Configure routes
    app.get('/', (req, res) => res.send('Hello World'));
    
    // Start server
    app.listen(port, () => {
      console.log(`Server running on http://localhost:${port}`);
    });
  } catch (error) {
    console.error('Failed to start server:', error.message);
    process.exit(1);
  }
}

createServer();

Python Integration

#!/usr/bin/env python3
import subprocess
import sys

def clear_port(port):
    """Clear a port using portclear via subprocess."""
    try:
        subprocess.run(
            ['npx', 'portclear', '--quiet', str(port)],
            check=True,
            capture_output=True
        )
        return True
    except subprocess.CalledProcessError:
        return False

# Usage in Flask/Django
if __name__ == '__main__':
    PORT = 5000
    
    if clear_port(PORT):
        print(f'Port {PORT} cleared successfully')
    
    # Start your Flask/Django app
    # app.run(port=PORT)

Package.json Scripts

{
  "scripts": {
    "clean": "portclear --quiet 3000 8080",
    "predev": "npm run clean",
    "dev": "next dev",
    "prestart": "portclear -q 3000",
    "start": "node server.js",
    "test": "portclear -q 3001 && jest",
    "docker:clean": "portclear 2375 2376 5000-5010"
  }
}

Makefile Integration

.PHONY: clean dev prod

clean:
	@npx portclear --quiet 3000 8080 || true

dev: clean
	@npm run dev

prod: clean
	@npm start

test: clean
	@npm test

Docker Compose

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    command: >
      sh -c "npx portclear -q 3000 && npm start"

Advanced Scenarios

Port Range Management

// Kill all ports in development range
async function cleanDevPorts() {
  const ports = Array.from({ length: 11 }, (_, i) => 3000 + i);
  
  const results = await Promise.allSettled(
    ports.map(port => portclear(port, { quiet: true }))
  );
  
  const killed = results.filter(r => r.status === 'fulfilled').length;
  console.log(`Cleaned ${killed} out of ${ports.length} ports`);
}

Graceful Shutdown

// Implement graceful shutdown with timeout
async function gracefulKill(port, timeout = 5000) {
  try {
    // Try normal termination first
    await portclear(port);
    return true;
  } catch (error) {
    // If failed, try with process tree
    console.log('Attempting force kill with process tree...');
    await portclear(port, { tree: true });
    return true;
  }
}

Health Check Integration

// Health check before starting service
async function healthCheck(port) {
  const result = await portclear(port, { list: true });
  
  if (!result.error) {
    console.warn(`WARN: Port ${port} is already in use by ${result.name}`);
    return false;
  }
  
  return true; // Port is free
}

Platform Compatibility

Operating System Support

Platform	Version	Support Level	Commands Used
Windows	7, 8, 10, 11, Server	Full	`netstat -ano`, `taskkill /PID /F`
macOS	10.12+	Full	`lsof -ti :PORT`, `kill -9`
Linux	All major distributions	Full	`lsof -ti :PORT`, `kill -9`
Unix	FreeBSD, OpenBSD	Full	`lsof -ti :PORT`, `kill -9`

Node.js Compatibility

Minimum Version: Node.js 14.0.0
Recommended: Node.js 18.0.0 or later
LTS Support: All current LTS versions

Protocol Support

TCP: Full support (default)
UDP: Full support (use -m udp flag)
IPv4: Full support
IPv6: Depends on OS implementation

Performance & Benchmarks

Execution Speed

Average execution time (single port):
  Windows:  ~150ms
  macOS:    ~80ms
  Linux:    ~70ms
  
Port range (10 ports):
  Sequential: ~800ms
  Parallel:   ~200ms (implementation dependent)

Resource Usage

Memory:     < 15 MB
CPU:        Minimal (< 5% during execution)
Disk I/O:   Negligible

Package Metrics

Package size:     10.3 KB (packed)
Unpacked size:    33.5 KB
Install time:     < 2 seconds
Dependencies:     0

Troubleshooting

Common Issues & Solutions

Permission Denied Error

Problem: EACCES: permission denied for port 3000

Solution:

# macOS/Linux
sudo npx portclear 3000

# Windows (run PowerShell/CMD as Administrator)
npx portclear 3000

Explanation: Some ports (especially < 1024) require elevated privileges on Unix-based systems.

Port Still in Use After Termination

Problem: Port remains occupied after running portclear

Possible Causes:

Process takes time to release the port (TIME_WAIT state)
Multiple processes using the same port
Child processes not terminated

Solutions:

# Solution 1: Wait and verify
portclear -l 3000  # Check if process is gone
sleep 2            # Wait for TCP cleanup
portclear -l 3000  # Verify again

# Solution 2: Use process tree kill
portclear --tree 3000

# Solution 3: Kill port range
portclear 3000-3002  # Kill related ports

Invalid Port Number

Problem: Error: Invalid port number

Valid port range: 1 - 65535

# Invalid
portclear 0       # Too low
portclear 99999   # Too high
portclear abc     # Non-numeric

# Valid
portclear 3000
portclear 1-65535

Command Not Found

Problem: portclear: command not found

Solutions:

# Solution 1: Use npx (no installation needed)
npx portclear 3000

# Solution 2: Install globally
npm install -g portclear
portclear 3000

# Solution 3: Use in package.json scripts
npm run clean  # If configured in scripts

Debug Mode

For troubleshooting, use verbose mode to see detailed information:

# Enable verbose output
portclear -v 3000

# Combine with list mode for inspection
portclear -l -v 3000

# JSON output for programmatic debugging
portclear --json 3000 | jq '.'

Getting Help

Documentation: GitHub README
Issues: GitHub Issues
npm Package: npmjs.com/package/portclear

Migration Guide

From kill-port

# Old (kill-port)
npx kill-port 3000
npx kill-port 3000 3001 3002

# New (portclear)
npx portclear 3000
npx portclear 3000 3001 3002
# or
npx portclear 3000-3002

From killport

# Old (killport)
npx killport 3000

# New (portclear)
npx portclear 3000

# With options
npx portclear --quiet 3000  # Silent mode
npx portclear --list 3000   # Preview mode

From fuser (Linux)

# Old (fuser)
fuser -k 3000/tcp

# New (portclear)
npx portclear 3000
npx portclear -m tcp 3000  # Explicit TCP

Contributing

We welcome contributions from the community! Here's how you can help:

Development Setup

# Clone repository
git clone https://github.com/mreshank/portclear.git
cd portclear

# Install dependencies (none for runtime, dev only)
npm install

# Run tests
npm test

# Test CLI locally
node cli.js --help

Guidelines

Code Style: Follow existing patterns and conventions
Tests: Add tests for new features
Documentation: Update README.md for user-facing changes
Commits: Use clear, descriptive commit messages
Pull Requests: One feature per PR, include rationale

Testing

# Run full test suite
npm test

# Test specific port
node cli.js -l 3000

# Test with actual process
node test/test.js

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Acknowledgments

Built with care for the developer community. Special thanks to all contributors and users who have helped improve this tool.

Repository: github.com/mreshank/portclear
npm Package: npmjs.com/package/portclear
Author: Eshank Tyagi • GitHub

Made for developers, by developers
Supports every language • Works everywhere • Free forever

⭐ Star on GitHub • 📦 View on npm • 🐛 Report Bug

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
test		test
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
cli.js		cli.js
example.js		example.js
index.d.ts		index.d.ts
index.js		index.js
package.json		package.json
publish-all.js		publish-all.js

Folders and files

Latest commit

History

Repository files navigation

portclear

Table of Contents

Overview

Key Highlights

Why portclear?

Technical Advantages

Design Philosophy

Installation

Quick Install (Recommended)

Global Installation

Project Dependency

Available Package Aliases

Quick Start

Basic Usage

Common Scenarios

CLI Reference

Command Syntax

Options

Usage Examples

API Documentation

JavaScript/TypeScript API

Basic Usage

Advanced Options

TypeScript Support

Type Definitions

Error Handling

Preview Before Termination

Universal Language Support

Supported Languages & Frameworks

How It Works

Advanced Usage

Integration Patterns

Express.js Application

Python Integration

Package.json Scripts

Makefile Integration

Docker Compose

Advanced Scenarios

Port Range Management

Graceful Shutdown

Health Check Integration

Platform Compatibility

Operating System Support

Node.js Compatibility

Protocol Support

Performance & Benchmarks

Execution Speed

Resource Usage

Package Metrics

Troubleshooting

Common Issues & Solutions

Debug Mode

Getting Help

Migration Guide

From kill-port

From killport

From fuser (Linux)

Contributing

Development Setup

Guidelines

Testing

License

Acknowledgments

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages