# PORTFINDER
[](https://www.python.org/)
[](LICENSE)
[](https://pypi.org/project/portfinder/)
Portfinder is a powerful asynchronous port scanner for Python that allows you to quickly scan multiple targets with flexible configuration options.
## Navigation
- [Features](#features)
- [Installation](#installation-as-python-library)
- [Command Line Usage](#command-line-usage)
- [Basic Scan](#run-basic-scan)
- [Advanced Scan](#advanced-scan)
- [Arguments](#arguments)
- [Python API](#basic-python-usage)
- [Output Formats](#output-files-format)
- [License](#license)
## Features
- Scan multiple IPs, CIDR ranges or domains
- Custom port ranges support (e.g., `1-1000,3389,8080`)
- Protocol-specific scanning (TCP, UDP, HTTP, HTTPS)
- High-performance async I/O implementation
- Multiple output formats (JSON, JSON Lines, plain text)
- Quiet mode for scripting
## Installation as Python Library [](https://pypi.org/project/portfinder/)
```commandline
pip install portfinder
```
### run basic scan
```commandline
portfinder -t example.com
```
### advanced scan
```commandline
portfinder -t 192.168.1.1,10.0.0.0/24,example.com -p 1-1024,3389,8080 -P http -T 1.5 -c 500 -tps 300 -o scan_results -j
```
| Argument | Description |
|-------------------------|---------------------------------------------------------|
| `-t`, `--target` | Target IP/CIDR/domain (comma-separated) (required) |
| `-p`, `--ports` | Ports to scan (default: `80,443,53`) |
| `-P`, `--protocol` | Protocol to check (tcp, udp, http, https) |
| `-T`, `--timeout` | Timeout in seconds (default: 2.0) |
| `-c`, `--concurrency` | Maximum concurrent connections per host (default: 300) no more than ~500-1000 on CPU cores |
| `-o`, `--outfile` | Output file path (without extension) |
| `-j`, `--js` | Output in JSON format |
| `-jl`, `--jsl` | Output in JSON Lines format |
| `-q`, `--quiet` | Disable all stdout output |
### basic python usage
```python
from portfinder.scanner import Scanner
from portfinder.dto import Protocol, Result
async def run_scan():
...
scanner = Scanner(
target="0.0.0.0",
ports="80-23000",
protocol=Protocol.HTTP,
timeout=4.0,
concurrency=400,
ip_pool_size=200,
)
results: list[Result] = await scanner.run()
...
```
* `Result` is a active port item (dataclass) with attributes:
* host: str
* port: int
* ip_version: IpVersion
* protocols: list[Protocol]
* `Protocol` enum:
* HTTP,
* HTTPS,
* TCP,
* UDP
## output files format:
* txt file
```txt
0.0.0.0:21 [ipv4] (tcp)
```
* json file
```json
[
{
"host": "0.0.0.0",
"port": 21,
"ip_version": "ipv4",
"protocols": [
[
"tcp"
]
]
}
]
```
* jsonl file
```json lines
{"host": "0.0.0.0", "port": 53, "ip_version": "ipv4", "protocols": [["tcp"]]}
```
### powered by lynkey.io
License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/stanley0707/portfinder",
"name": "portfinder",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "port, scanner, network, security",
"author": "Stanislav Shilov",
"author_email": "s.shilow@lynkey.io",
"download_url": "https://files.pythonhosted.org/packages/47/de/38d0b57b17a00c050a1a6b9e0379ba665dc2a996e56937aa4fc7f502604b/portfinder-0.1.4.tar.gz",
"platform": null,
"description": "# PORTFINDER\n\n[](https://www.python.org/)\n[](LICENSE)\n[](https://pypi.org/project/portfinder/)\n\nPortfinder is a powerful asynchronous port scanner for Python that allows you to quickly scan multiple targets with flexible configuration options.\n\n## Navigation\n- [Features](#features)\n- [Installation](#installation-as-python-library)\n- [Command Line Usage](#command-line-usage)\n - [Basic Scan](#run-basic-scan)\n - [Advanced Scan](#advanced-scan)\n - [Arguments](#arguments)\n- [Python API](#basic-python-usage)\n- [Output Formats](#output-files-format)\n- [License](#license)\n\n## Features\n- Scan multiple IPs, CIDR ranges or domains\n- Custom port ranges support (e.g., `1-1000,3389,8080`)\n- Protocol-specific scanning (TCP, UDP, HTTP, HTTPS)\n- High-performance async I/O implementation\n- Multiple output formats (JSON, JSON Lines, plain text)\n- Quiet mode for scripting\n\n## Installation as Python Library [](https://pypi.org/project/portfinder/)\n```commandline\npip install portfinder\n```\n\n### run basic scan\n```commandline\nportfinder -t example.com\n```\n\n### advanced scan\n```commandline\nportfinder -t 192.168.1.1,10.0.0.0/24,example.com -p 1-1024,3389,8080 -P http -T 1.5 -c 500 -tps 300 -o scan_results -j\n```\n\n| Argument | Description |\n|-------------------------|---------------------------------------------------------|\n| `-t`, `--target` | Target IP/CIDR/domain (comma-separated) (required) |\n| `-p`, `--ports` | Ports to scan (default: `80,443,53`) |\n| `-P`, `--protocol` | Protocol to check (tcp, udp, http, https) |\n| `-T`, `--timeout` | Timeout in seconds (default: 2.0) |\n| `-c`, `--concurrency` | Maximum concurrent connections per host (default: 300) no more than ~500-1000 on CPU cores |\n| `-o`, `--outfile` | Output file path (without extension) |\n| `-j`, `--js` | Output in JSON format |\n| `-jl`, `--jsl` | Output in JSON Lines format |\n| `-q`, `--quiet` | Disable all stdout output |\n\n### basic python usage\n\n```python\nfrom portfinder.scanner import Scanner\nfrom portfinder.dto import Protocol, Result\n\nasync def run_scan():\n ...\n scanner = Scanner(\n target=\"0.0.0.0\",\n ports=\"80-23000\",\n protocol=Protocol.HTTP,\n timeout=4.0,\n concurrency=400,\n ip_pool_size=200,\n )\n results: list[Result] = await scanner.run()\n ...\n```\n* `Result` is a active port item (dataclass) with attributes:\n * host: str\n * port: int\n * ip_version: IpVersion\n * protocols: list[Protocol]\n* `Protocol` enum:\n * HTTP,\n * HTTPS,\n * TCP,\n * UDP\n\n## output files format:\n* txt file\n```txt\n0.0.0.0:21 [ipv4] (tcp)\n```\n* json file\n```json\n[\n {\n \"host\": \"0.0.0.0\",\n \"port\": 21,\n \"ip_version\": \"ipv4\",\n \"protocols\": [\n [\n \"tcp\"\n ]\n ]\n }\n]\n```\n* jsonl file\n```json lines\n{\"host\": \"0.0.0.0\", \"port\": 53, \"ip_version\": \"ipv4\", \"protocols\": [[\"tcp\"]]}\n```\n### powered by lynkey.io\nLicense\nMIT\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "port scanner",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://github.com/stanley0707/portfinder",
"Repository": "https://github.com/stanley0707/portfinder"
},
"split_keywords": [
"port",
" scanner",
" network",
" security"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9336540a98c1546baee62e29363e322ca2066dfb3f6beb9c4271d7d8f9a6d0a0",
"md5": "bd06a285018635d757128a4a210a08f2",
"sha256": "80897c6adc360011399a6f4f9812fd4c283ad8c6d5b9d786a40b8285a7942953"
},
"downloads": -1,
"filename": "portfinder-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bd06a285018635d757128a4a210a08f2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 8605,
"upload_time": "2025-07-23T11:45:04",
"upload_time_iso_8601": "2025-07-23T11:45:04.546605Z",
"url": "https://files.pythonhosted.org/packages/93/36/540a98c1546baee62e29363e322ca2066dfb3f6beb9c4271d7d8f9a6d0a0/portfinder-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "47de38d0b57b17a00c050a1a6b9e0379ba665dc2a996e56937aa4fc7f502604b",
"md5": "aa9ac1099daddb822c6aafdbcccd3f5a",
"sha256": "c88be075e4fac142670883b4d343535e2ed4ddb92450767beb09506a96f6c2af"
},
"downloads": -1,
"filename": "portfinder-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "aa9ac1099daddb822c6aafdbcccd3f5a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 7446,
"upload_time": "2025-07-23T11:45:05",
"upload_time_iso_8601": "2025-07-23T11:45:05.704776Z",
"url": "https://files.pythonhosted.org/packages/47/de/38d0b57b17a00c050a1a6b9e0379ba665dc2a996e56937aa4fc7f502604b/portfinder-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 11:45:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stanley0707",
"github_project": "portfinder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "portfinder"
}
JSON
