{"id":7630,"library":"python-nmap","title":"python-nmap","description":"python-nmap is a Python library that provides a convenient interface for interacting with the Nmap security scanner. It allows Python scripts to build and execute Nmap scans, parse scan results, and automate network discovery and vulnerability assessment tasks. The library is currently at version 0.7.1 and has an irregular release cadence, with updates addressing bugs and improving compatibility.","status":"active","version":"0.7.1","language":"en","source_language":"en","source_url":"https://github.com/nmmapper/python3-nmap","tags":["nmap","network-scanning","security","pentesting","network","automation"],"install":[{"cmd":"pip install python-nmap","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"This 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.","package":"Nmap (system tool)","optional":false}],"imports":[{"note":"Importing 'nmap' directly from 'nmap' can lead to confusion if you name your script 'nmap.py'. The standard is to import the top-level 'nmap' module and access PortScanner as an attribute.","wrong":"from nmap import nmap","symbol":"PortScanner","correct":"import nmap\nnm = nmap.PortScanner()"}],"quickstart":{"code":"import nmap\nimport os\n\n# Instantiate the PortScanner\nnm = nmap.PortScanner()\n\n# Define target and ports\ntarget_host = os.environ.get('SCAN_TARGET_IP', '127.0.0.1')\nscan_ports = os.environ.get('SCAN_PORTS', '22-443')\n\ntry:\n    # Perform a scan\n    nm.scan(target_host, scan_ports)\n\n    # Iterate through scanned hosts\n    for host in nm.all_hosts():\n        print(f'Host : {host} ({nm[host].hostname()})')\n        print(f'State : {nm[host].state()}')\n        for proto in nm[host].all_protocols():\n            print('----------')\n            print(f'Protocol : {proto}')\n\n            lport = nm[host][proto].keys()\n            for port in lport:\n                print(f'port : {port}\\tstate : {nm[host][proto][port]['state']}')\nexcept nmap.nmap.PortScannerError as e:\n    print(f\"Error during scan: {e}\")\n    print(\"Please ensure Nmap is installed and in your system's PATH.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Install 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.","message":"Nmap 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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Rename 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.","message":"Naming 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refactor asynchronous scan logic to use `PortScanner().iterscan()` or implement custom `asyncio` with `subprocess` calls. Review the latest GitHub README for current async patterns.","message":"Older 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.","severity":"deprecated","affected_versions":"< 0.6.3 (roughly 2018-2019)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the Nmap security scanner on your operating system. For Linux (Debian/Ubuntu), use `sudo apt install nmap`. For Windows or macOS, download the installer from nmap.org. Verify Nmap is installed by running `nmap --version` in your terminal. Ensure its installation directory is in your system's PATH.","cause":"The Nmap executable (the system tool) is either not installed or not found in the system's PATH environment variable.","error":"('Nmap not found', <class 'nmap.nmap.PortScannerError'>)"},{"fix":"Rename your Python script file to something unique (e.g., `my_scanner.py`). If you still encounter the error, delete any `.pyc` files or `__pycache__` directories in your project.","cause":"You have a Python file named `nmap.py` in your project directory or Python's import path, which conflicts with the installed `python-nmap` library. Python imports your local file instead of the library.","error":"AttributeError: module 'nmap' has no attribute 'PortScanner'"},{"fix":"Ensure the Nmap system tool is correctly installed and its executable is accessible in your system's PATH. On some systems, you might need to provide the full path to the nmap executable when instantiating PortScanner: `nm = nmap.PortScanner('/usr/local/bin/nmap')` (adjust path as needed).","cause":"This error often occurs when the `nmap` executable itself cannot be found or executed by the Python script, typically due to it not being in the system's PATH.","error":"OSError: [Errno 2] No such file or directory"}]}