Install & Compatibility
Where this runs
tested against v0.7.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.038s · 19.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.5s · import 0.033s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PortScanner
✓ from nmap import PortScanner
✗ import nmap
This quickstart demonstrates how to perform a basic port scan on a target IP address and then print the host information, state, and details for all discovered open ports and their services. It includes basic error handling for common Nmap-related issues.
import nmap
import os
# Instantiate the PortScanner
nm = nmap.PortScanner()
# Define target and ports
target_host = os.environ.get('SCAN_TARGET_IP', '127.0.0.1')
scan_ports = os.environ.get('SCAN_PORTS', '22-443')
try:
# Perform a scan
nm.scan(target_host, scan_ports)
# Iterate through scanned hosts
for host in nm.all_hosts():
print(f'Host : {host} ({nm[host].hostname()})')
print(f'State : {nm[host].state()}')
for proto in nm[host].all_protocols():
print('----------')
print(f'Protocol : {proto}')
lport = nm[host][proto].keys()
for port in lport:
print(f'port : {port}\tstate : {nm[host][proto][port]['state']}')
except nmap.nmap.PortScannerError as e:
print(f"Error during scan: {e}")
print("Please ensure Nmap is installed and in your system's PATH.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingNmap executable (the system tool) must be installed and in your system's PATH. This Python library is a wrapper and will not work if Nmap is not found. This is the most common reason for errors.fixInstall Nmap on your operating system (e.g., `sudo apt install nmap` on Debian/Ubuntu, or download from nmap.org for Windows/macOS) and ensure its executable path is configured correctly in your system's PATH environment variable.
affects: All versions
gotchaNaming your Python script `nmap.py` will cause an `AttributeError: module 'nmap' has no attribute 'PortScanner'`. This is because Python will try to import your own script instead of the installed `python-nmap` library.fixRename your Python script to something other than `nmap.py` (e.g., `my_scanner.py`). If the problem persists, delete any `.pyc` files or `__pycache__` directories related to the misnamed script.
affects: All versions
deprecatedOlder versions of `python-nmap` included `PortScannerAsync` for asynchronous scanning. This class was removed, and asynchronous operations are now typically handled via the `iterscan` method within the `PortScanner` class, or by using Python's `asyncio` with `subprocess` for more fine-grained control.fixRefactor asynchronous scan logic to use `PortScanner().iterscan()` or implement custom `asyncio` with `subprocess` calls. Review the latest GitHub README for current async patterns.
affects: < 0.6.3 (roughly 2018-2019)
Upgrade
Version history
0.7.1latest on PyPI · released Oct 26, 2021
Audit
Dependencies
Nmap (system tool)requiredThis Python library is a wrapper around the Nmap executable. Nmap must be installed on your system and accessible in the system's PATH for python-nmap to function.