# 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 |
|-----------------------|-------------------------------------------------------------------------------------------|
| `-f`, `--file` | Target txt file with IP/CIDR/domain (new-line-separated) |
| `-t`, `--target` | Target IP/CIDR/domain (comma-separated) |
| `-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 |
| `-u`, `--uvloop_disable` | Disable async uvloop (move to standart asyncio event loop) |
### usage with docker
```commandline
docker run --rm stanley0507/portfinder:latest -t 192.168.1.1 -p 1-1000
```
### usage with input file with docker
```commandline
docker run -v $(pwd)/results:/data --rm stanley0507/portfinder:latest -f /data/input_data.txt -p 1-9000 -o scan_result_ -jl
```
input_data.txt example
```txt
192.168.1.1
example.com
```
### 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/31/87/a39848e008b0c0bac6ebb57a2a9875faad42160a5373df3bf3d3f4565d1c/portfinder-0.1.7.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| `-f`, `--file` | Target txt file with IP/CIDR/domain (new-line-separated) |\n| `-t`, `--target` | Target IP/CIDR/domain (comma-separated) |\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| `-u`, `--uvloop_disable` | Disable async uvloop (move to standart asyncio event loop) |\n\n\n### usage with docker\n```commandline\ndocker run --rm stanley0507/portfinder:latest -t 192.168.1.1 -p 1-1000\n```\n### usage with input file with docker\n```commandline\ndocker run -v $(pwd)/results:/data --rm stanley0507/portfinder:latest -f /data/input_data.txt -p 1-9000 -o scan_result_ -jl\n```\ninput_data.txt example\n```txt\n192.168.1.1\nexample.com\n```\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.7",
"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": "cb4c0e726d6ef096b0e06c9c0aab5b39389957b104cb1fc720fe0da73da4d140",
"md5": "ee00cb51b2335687b9dd451e6f30697d",
"sha256": "1c9c756be8079ae550729e9fce0c80b7e6e231f88f7cc06278756190bb443e83"
},
"downloads": -1,
"filename": "portfinder-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ee00cb51b2335687b9dd451e6f30697d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 10262,
"upload_time": "2025-07-25T13:30:58",
"upload_time_iso_8601": "2025-07-25T13:30:58.221748Z",
"url": "https://files.pythonhosted.org/packages/cb/4c/0e726d6ef096b0e06c9c0aab5b39389957b104cb1fc720fe0da73da4d140/portfinder-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3187a39848e008b0c0bac6ebb57a2a9875faad42160a5373df3bf3d3f4565d1c",
"md5": "4870c8163ae410c2da7c11e66ccdc86e",
"sha256": "452839a5f5a3e2189ef7a2ded7b4c82b965ee1de03a2ba07d2cd70ffb9321378"
},
"downloads": -1,
"filename": "portfinder-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "4870c8163ae410c2da7c11e66ccdc86e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 9938,
"upload_time": "2025-07-25T13:30:59",
"upload_time_iso_8601": "2025-07-25T13:30:59.500154Z",
"url": "https://files.pythonhosted.org/packages/31/87/a39848e008b0c0bac6ebb57a2a9875faad42160a5373df3bf3d3f4565d1c/portfinder-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 13:30:59",
"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
