Metadata-Version: 2.5
Name: portkill
Version: 0.1.0
Summary: Find and kill whatever process is using a port. Works on Windows, macOS and Linux.
License-Expression: MIT
Requires-Python: >=3.9
Requires-Dist: psutil>=5.9
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# portkill

Find and kill whatever process is using a port. Works on Windows, macOS and Linux.

```
$ portkill 3000
┌──────┬───────┬──────────┬───────┬────────┬──────────────────────┐
│ Port │   PID │ Name     │ Proto │ State  │ Command              │
├──────┼───────┼──────────┼───────┼────────┼──────────────────────┤
│ 3000 │ 41872 │ node.exe │ TCP   │ LISTEN │ node server.js       │
└──────┴───────┴──────────┴───────┴────────┴──────────────────────┘
Kill 1 process? [y/N]: y
killed: node.exe (PID 41872, port 3000)
```

## Install

```
pipx install portkill
# or
uv tool install portkill
```

## Usage

```
portkill 3000                 # show what's on port 3000, ask, then kill it
portkill 3000,8080            # several ports
portkill 3000-3005 8080       # ranges, in any mix
portkill 3000 --yes           # don't ask
portkill 3000 --list          # only show, kill nothing
portkill 3000 --force         # kill immediately instead of asking it to exit first
```

By default portkill asks the process to exit and waits up to `--timeout`
seconds (default 3) before killing it outright.

## Safety

- Asks before killing anything unless you pass `--yes`.
- Never kills critical system processes (`System`, `lsass.exe`, `launchd`,
  `systemd`, ...) or itself, even with `--force`.
- If a process belongs to another user, portkill tells you to rerun as
  administrator / with `sudo`.

## Exit codes

| Code | Meaning                                  |
| ---- | ---------------------------------------- |
| 0    | Ports are free (or nothing was running)  |
| 1    | Some processes could not be killed       |
| 2    | Bad input                                |

## License

MIT
