{"id":51008403,"url":"https://github.com/voidd0/portcheck","last_synced_at":"2026-06-20T23:31:03.132Z","repository":{"id":354536275,"uuid":"1223262712","full_name":"voidd0/portcheck","owner":"voidd0","description":"see what's listening on local ports. faster than netstat, simpler than ss.","archived":false,"fork":false,"pushed_at":"2026-05-19T03:54:05.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T04:38:56.773Z","etag":null,"topics":["cli","devtools","javascript","lsof-alternative","networking","nodejs","ports","tcp","udp"],"latest_commit_sha":null,"homepage":"https://tools.voiddo.com/portcheck/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voidd0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":["https://voiddo.com/contact/","https://scrb.voiddo.com/"]}},"created_at":"2026-04-28T06:47:49.000Z","updated_at":"2026-05-19T03:54:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/voidd0/portcheck","commit_stats":null,"previous_names":["voidd0/portcheck"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/voidd0/portcheck","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voidd0%2Fportcheck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voidd0%2Fportcheck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voidd0%2Fportcheck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voidd0%2Fportcheck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voidd0","download_url":"https://codeload.github.com/voidd0/portcheck/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voidd0%2Fportcheck/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34589204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","devtools","javascript","lsof-alternative","networking","nodejs","ports","tcp","udp"],"created_at":"2026-06-20T23:31:00.710Z","updated_at":"2026-06-20T23:31:03.127Z","avatar_url":"https://github.com/voidd0.png","language":"JavaScript","funding_links":["https://voiddo.com/contact/","https://scrb.voiddo.com/"],"categories":[],"sub_categories":[],"readme":"# portcheck\n\n[![npm version](https://img.shields.io/npm/v/@v0idd0/portcheck.svg?color=A0573A)](https://www.npmjs.com/package/@v0idd0/portcheck)\n[![npm downloads](https://img.shields.io/npm/dw/@v0idd0/portcheck.svg?color=1F1A14)](https://www.npmjs.com/package/@v0idd0/portcheck)\n[![License: MIT](https://img.shields.io/badge/license-MIT-A0573A.svg)](LICENSE)\n[![Node ≥14](https://img.shields.io/badge/node-%E2%89%A514-1F1A14)](package.json)\n\n**[Homepage](https://tools.voiddo.com/portcheck/?ref=portcheck-readme)** · **[Compare with lsof](https://tools.voiddo.com/portcheck/compare/lsof/?ref=portcheck-readme)** · **[GitHub](https://github.com/voidd0/portcheck)** · **[npm](https://www.npmjs.com/package/@v0idd0/portcheck)** · **[All tools](https://tools.voiddo.com/?ref=portcheck-catalog-readme)** · **[Contact](mailto:support@voiddo.com)**\n\n---\n\nSee what's listening on your local ports. Fast. Zero deps. Reads `/proc` directly on Linux, falls back to `lsof` on macOS/BSD.\n\nIf you are typing `lsof -i :3000` out of habit, start with the compare page: [portcheck vs lsof](https://tools.voiddo.com/portcheck/compare/lsof/?ref=portcheck-readme).\n\n```\n$ portcheck\nport   proto  command         pid     address\n80     tcp    nginx           1923    0.0.0.0\n443    tcp    nginx           1923    0.0.0.0\n3000   tcp    node            28471   127.0.0.1\n5432   tcp    postgres        1923    127.0.0.1\n8000   tcp    uvicorn         2728014 127.0.0.1\n```\n\n## Why portcheck\n\nYou started a dev server two windows ago. You started another one in this window. They both bound to `:3000`. You don't remember which is which. The fix is `lsof -i :3000`, but `lsof` is slow on machines with many file descriptors and the output is full of fields you don't need. `netstat -tlnp` was deprecated five distros ago. `ss -ltnp` is fast but its column alignment was last touched in the kernel 3.x era.\n\n`portcheck` is what those commands would look like if you wrote them today: column-aligned, sorted by port, no sudo for your own processes, instant on a laptop with 50K open fds.\n\n## Install\n\n```bash\nnpm install -g @v0idd0/portcheck\n```\n\n## Usage\n\n```bash\n# All listening ports\nportcheck\n\n# Filter to a single port\nportcheck 443\n\n# Filter to a range\nportcheck 8000-9000\n\n# JSON for piping\nportcheck --json | jq '.[] | select(.command == \"node\")'\n```\n\n## Compared to alternatives\n\n| tool | speed on 50K fds | sudo for self | output legibility | macOS support |\n|---|---|---|---|---|\n| portcheck | \u003c50ms | no | aligned, sorted by port | via `lsof` fallback |\n| `lsof -i -P -n` | 2-3s | yes (for others) | dense, hard to scan | yes |\n| `ss -ltnp` | \u003c100ms | yes (for cmd) | terse columns | no |\n| `netstat -tlnp` | varies | sometimes | 1990s formatting | deprecated |\n\nIf you regularly investigate ports across machines you don't own (oncall, debugging others' processes), `lsof -i` is still the canonical answer. For your own laptop and your own processes, portcheck is faster typing and faster reading.\n\n## FAQ\n\n**Why doesn't it need sudo?** On Linux it parses `/proc/\u003cpid\u003e/net/tcp` and `/proc/\u003cpid\u003e/cmdline` for processes you own, which doesn't require elevation. To see ports owned by *other* users, run with sudo — same rule as `lsof`.\n\n**Does it show UDP?** Yes when you ask: `portcheck --proto udp` or `--proto all`. Default is TCP because that's what people actually search for.\n\n**What about systemd-managed sockets that no process holds open yet?** Not visible until the activated process binds. That's a kernel-level signal portcheck deliberately doesn't try to surface — `systemctl list-sockets` is the right tool there.\n\n**Why no docker integration?** Containers running on your host do appear under their PID. If you want container-aware port mapping, `docker ps` shows the published-port column already.\n\n## Programmatic API\n\n```javascript\nimport { list, filterRange, format } from '@v0idd0/portcheck';\n\nconst all = list();\nconst webPorts = filterRange(all, '80-443');\nconsole.log(format(webPorts));\n```\n\n## Tips\n\n- **Pipe to `awk` for ad-hoc filters** — `portcheck --json | jq '.[] | select(.address == \"0.0.0.0\")'` finds anything bound to a public interface, useful when you wonder why your firewall rule isn't doing what you thought.\n- **In docker-compose dev workflows** — run `portcheck` on the host to confirm published ports actually landed; container-internal ports won't appear (they live in the container's net namespace), which is itself a useful signal.\n- **As a teardown helper** — `portcheck --json | jq '.[] | select(.command == \"node\") | .pid' | xargs kill` is the no-ceremony version of \"kill all my orphaned dev servers\". Use with care.\n\n## Compare with lsof\n\n`lsof` is the classic Swiss-army answer when you want file-descriptor depth. `portcheck` is the quicker answer when the only question is \"what is listening on this port?\" The compare page spells out the difference in plain language: [portcheck vs lsof](https://tools.voiddo.com/portcheck/compare/lsof/?ref=portcheck-readme).\n\n## From the same studio\n\nvøiddo builds sharp, free-forever CLIs for debugging production-ish messes without opening a GUI:\n\n- [`@v0idd0/dotdig`](https://tools.voiddo.com/dotdig/?ref=portcheck-related-dotdig-readme) — DNS lookup formatted for humans, not RFC archaeology\n- [`@v0idd0/sslcheck`](https://tools.voiddo.com/sslcheck/?ref=portcheck-related-sslcheck-readme) — inspect TLS cert expiry, SANs, chain depth, and key strength\n- [`@v0idd0/httpwut`](https://tools.voiddo.com/httpwut/?ref=portcheck-related-httpwut-readme) — trace what an HTTP request actually did on the wire\n- [`@v0idd0/timecheck`](https://tools.voiddo.com/timecheck/?ref=portcheck-related-timecheck-readme) — convert and rewrite timestamps without leaving the terminal\n\nFull catalog: [tools.voiddo.com](https://tools.voiddo.com/?ref=portcheck-catalog-readme). Full lineup doc: [`from-the-studio.md`](from-the-studio.md).\n\n## From the same studio\n\n- **[@v0idd0/jsonyo](https://www.npmjs.com/package/@v0idd0/jsonyo)** — JSON swiss army knife, 18 commands, zero limits\n- **[@v0idd0/envguard](https://www.npmjs.com/package/@v0idd0/envguard)** — stop shipping `.env` drift to staging\n- **[@v0idd0/depcheck](https://www.npmjs.com/package/@v0idd0/depcheck)** — find unused dependencies in one command\n- **[@v0idd0/gitstats](https://www.npmjs.com/package/@v0idd0/gitstats)** — git repo analytics, one command\n- **[View all tools →](https://voiddo.com/tools/)**\n\n## License\n\nMIT.\n\n---\n\nBuilt by [vøiddo](https://voiddo.com/) — a small studio shipping AI-flavoured products, free dev tools, Chrome extensions and weird browser games.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoidd0%2Fportcheck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoidd0%2Fportcheck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoidd0%2Fportcheck/lists"}