# portndock
A cross-platform terminal tool for developers to easily find and kill processes using ports. Perfect for fixing **"port already in use"** errors!
## Features
- **Find processes by port** - See what's using any port
- **Docker aware** - Handles containers intelligently
- **Interactive TUI** - Color-coded safety levels
- **Related processes** - Find Electron renderers and background processes
- **Safe by default** - Warns about dangerous processes
- **Cross-platform** - Windows, macOS, Linux
- **Zero dependencies** - Pure Python
## Installation
```bash
# Recommended (handles environment isolation)
pipx install portndock
# Upgrade to latest version
pipx upgrade portndock
# Alternatives
pip install portndock --user
python3 -m venv env && source env/bin/activate && pip install portndock
```
## Local Development
```bash
# Clone the repository
git clone https://github.com/decentaro/portndock.git
cd portndock
# Run directly from source (no installation needed)
python3 -m portndock
# or with sudo for system processes
sudo python3 -m portndock ui
# Install in development mode (optional)
pip install -e .
```
## Usage
```bash
# Interactive mode (recommended)
portndock
# Command line
portndock kill --port 3000
portndock list
portndock free --port 8080
```
## Interactive Controls
- **↑/↓** - Navigate • **Enter** - Kill process • **D** - Stop container
- **V** - Filter ports • **P** - Filter protocols • **E** - Toggle related processes
- **X** - Toggle IPv6 • **?** - Help • **Q** - Quit
## Color Coding
- **Blue** - Docker containers (safe)
- **Green** - Your processes (safe)
- **Yellow** - System processes (careful)
- **Red** - Critical processes (danger)
## Examples
```bash
portndock ui # Interactive TUI
portndock kill --port 3000 # Kill by port
portndock kill --pid 12345 # Kill by PID
portndock list --protocol tcp # List TCP only
portndock free --port 8080 # Free port (Docker-aware)
```
## Requirements
Python 3.8+ • No dependencies • Cross-platform
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "portndock",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "port, process, docker, development, kill, terminal, tui",
"author": null,
"author_email": "Marc Carlo Dy <dymarccarlo@yahoo.com>",
"download_url": "https://files.pythonhosted.org/packages/e3/f2/01c3198a6f279e709f68bed4fbd650e7e02a2f56469d0e60ea56ba8b1833/portndock-1.0.2.tar.gz",
"platform": null,
"description": "# portndock\n\nA cross-platform terminal tool for developers to easily find and kill processes using ports. Perfect for fixing **\"port already in use\"** errors!\n\n## Features\n\n- **Find processes by port** - See what's using any port\n- **Docker aware** - Handles containers intelligently \n- **Interactive TUI** - Color-coded safety levels\n- **Related processes** - Find Electron renderers and background processes\n- **Safe by default** - Warns about dangerous processes\n- **Cross-platform** - Windows, macOS, Linux\n- **Zero dependencies** - Pure Python\n\n## Installation\n\n```bash\n# Recommended (handles environment isolation)\npipx install portndock\n\n# Upgrade to latest version\npipx upgrade portndock\n\n# Alternatives\npip install portndock --user\npython3 -m venv env && source env/bin/activate && pip install portndock\n```\n\n## Local Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/decentaro/portndock.git\ncd portndock\n\n# Run directly from source (no installation needed)\npython3 -m portndock\n# or with sudo for system processes\nsudo python3 -m portndock ui\n\n# Install in development mode (optional)\npip install -e .\n```\n\n## Usage\n\n```bash\n# Interactive mode (recommended)\nportndock\n\n# Command line\nportndock kill --port 3000\nportndock list\nportndock free --port 8080\n```\n\n## Interactive Controls\n\n- **\u2191/\u2193** - Navigate \u2022 **Enter** - Kill process \u2022 **D** - Stop container\n- **V** - Filter ports \u2022 **P** - Filter protocols \u2022 **E** - Toggle related processes\n- **X** - Toggle IPv6 \u2022 **?** - Help \u2022 **Q** - Quit\n\n## Color Coding\n\n- **Blue** - Docker containers (safe)\n- **Green** - Your processes (safe)\n- **Yellow** - System processes (careful) \n- **Red** - Critical processes (danger)\n\n## Examples\n\n```bash\nportndock ui # Interactive TUI\nportndock kill --port 3000 # Kill by port\nportndock kill --pid 12345 # Kill by PID \nportndock list --protocol tcp # List TCP only\nportndock free --port 8080 # Free port (Docker-aware)\n```\n\n## Requirements\n\nPython 3.8+ \u2022 No dependencies \u2022 Cross-platform\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Dev-focused port watcher/killer with Docker awareness and live TUI",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/decentaro/portndock",
"Issues": "https://github.com/decentaro/portndock/issues",
"Repository": "https://github.com/decentaro/portndock"
},
"split_keywords": [
"port",
" process",
" docker",
" development",
" kill",
" terminal",
" tui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5d2482f09ab1eb66dfb7ca8930f1031287fecfffa8d03b5fa5b1a527455ca972",
"md5": "316035074c5ccdd6659d877e0ffd02b1",
"sha256": "050a3d8620423e737e9db92abb28b706dea19ddb74db1c63c29e76d040b3aa7c"
},
"downloads": -1,
"filename": "portndock-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "316035074c5ccdd6659d877e0ffd02b1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27731,
"upload_time": "2025-09-02T15:54:01",
"upload_time_iso_8601": "2025-09-02T15:54:01.488454Z",
"url": "https://files.pythonhosted.org/packages/5d/24/82f09ab1eb66dfb7ca8930f1031287fecfffa8d03b5fa5b1a527455ca972/portndock-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e3f201c3198a6f279e709f68bed4fbd650e7e02a2f56469d0e60ea56ba8b1833",
"md5": "1dae730b9feefc15c65483b27c1375a9",
"sha256": "c913ebdcd84e6d119dacb189ae3048d4e85eb91e8e637092e20efef05957950b"
},
"downloads": -1,
"filename": "portndock-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "1dae730b9feefc15c65483b27c1375a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 25256,
"upload_time": "2025-09-02T15:54:02",
"upload_time_iso_8601": "2025-09-02T15:54:02.902537Z",
"url": "https://files.pythonhosted.org/packages/e3/f2/01c3198a6f279e709f68bed4fbd650e7e02a2f56469d0e60ea56ba8b1833/portndock-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 15:54:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "decentaro",
"github_project": "portndock",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "portndock"
}
JSON
