Skip to main content

Simple port scanning utility at terminal

Project description


PyPI version   Python 3.x   PyPI license   Downloads

PortScan is a light-weight command line utility that allows user to conduct scanning over a range of IP addresses and port ranges with multi-threading. Helpful with finding local stuff like printer, headless raspberry pi, or scanning remote blocks for open ranges of ports.

Install: pip install portscan

Upgrade: pip install portscan --upgrade

Usage: portscan [] [-p 22,80-200 [-t 100 [-w 1 [-e]]]]

$ portscan -w 0.2
No IP string found, using local address
Local IP found to be, scanning entire block
Threads will wait for ping response for 0.2 seconds OPEN OPEN OPEN OPEN
Pinged 1024 ports

By default the command checks for your Local Area Network IP first, and then initiate a block wise search. specify IP if you want to search any other IP blocks. Note: This is not available before 0.2.1, please update or specify IP if you're using 0.2.0 and older

Use -w [float] to change timeout settings from default of 3 seconds: for LAN, this can be as low as 0.1. 1 is usually good enough for continental level connection.

To show more ports that have denied/refused connection, use -e, this will show you all ports that are not timed out.

$ portscan -w 0.5 -e
Threads will wait for ping response for 0.5 seconds ERRNO 61, Connection refused ERRNO 61, Connection refused ERRNO 61, Connection refused ERRNO 61, Connection refused ERRNO 61, Connection refused ERRNO 61, Connection refused ERRNO 61, Connection refused ERRNO 61, Connection refused OPEN
Pinged 1024 ports


ip: default and optional (since 0.2.1, required before 0.2.1) argument, can parse single IP, list of IP, IP blocks: # single IP # A 24 block, from to

[,] # The aforementioned 24 block and


-p, --port: port range, default 22,23,80, use , as a delimiter without space, support port range (e.g. 22-100,5000).

-t, --threadnum: thread numbers, default 500, as of now, thread number have a hard cap of 2048. More thread will increase performance on large scale scans.

-e, --show_refused: show connection errors other than timeouts, e.g. connection refused, permission denied with errno number as they happen.

-w, --wait: Wait time for socket to respond. If scanning LAN or relatively fast internet connection, this can be set to 1 or even 0.1 for faster (local) scanning, but this runs a risk of missing the open ports. Default to 3 seconds

-s, --stop_after: Number of open ports to be discovered after which scan would be gracefully stopped. Default is None for not stopping. Note that it will continue to finish what's left in the queue, so the number of open ports returned might be greater than the value passed in.

Python API

One can also use this portscan inside existing python scripts.

Consider following example for finding out adb port for Android device in LAN with static IP:

from portscan import PortScan
ip = ''
port_range = '5555,37000-44000'
scanner = PortScan(ip, port_range, thread_num=500, show_refused=False, wait_time=1, stop_after_count=True)
open_port_discovered =  # <----- actual scan
# run returns a list of (ip, open_port) tuples
adb_port = int(open_port_discovered[0][1])

# Usecase specific part
from adb_shell.adb_device import AdbDeviceTcp, AdbDeviceUsb
device1 = AdbDeviceTcp(ip, adb_port, default_transport_timeout_s=9)
device1.connect(rsa_keys=[python_rsa_signer], auth_timeout_s=0.1)  # adb connect
# shell exec
notifications_dump ='dumpsys notification').encode().decode('ascii','ignore')



Jamieson Becker: For coming up with a way to find local IP on stackoverflow, which I used:

Mihir Parikh: Thanks for picking up my ancient project and verifying/supporting Windows and adding flags/return. And for convincing me to wrap it up and putting it in a better place than 4 years ago.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

portscan-1.1.tar.gz (6.9 kB view hashes)

Uploaded source

Built Distribution

portscan-1.1-py3-none-any.whl (7.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page