{"id":8560,"library":"python3-nmap","title":"python3-nmap","description":"Python3-nmap converts Nmap commands into python3 methods making it very easy to use nmap in any of your python pentesting projects. It provides a Python 3 interface to the Nmap port scanner, enabling manipulation of scan results and automation of scanning tasks and reports. The library is actively maintained, with the latest stable release being 1.9.1.","status":"active","version":"1.9.1","language":"en","source_language":"en","source_url":"https://github.com/nmmapper/python3-nmap","tags":["nmap","security","pentesting","network scanning","port scanning","automation"],"install":[{"cmd":"pip install python3-nmap","lang":"bash","label":"Install via pip"},{"cmd":"sudo apt install nmap # On Debian/Ubuntu\nbrew install nmap # On macOS\n# Download and install from nmap.org for Windows","lang":"bash","label":"Install Nmap binary (essential dependency)"}],"dependencies":[{"reason":"This library is a wrapper around the Nmap binary; Nmap must be installed on the system and accessible in the PATH.","package":"nmap","optional":false},{"reason":"Requires Python 3.6 or higher.","package":"python3","optional":false}],"imports":[{"note":"The `nmap` import is for the older `python-nmap` library, which has a different API. `python3-nmap` uses `nmap3` for its main classes.","wrong":"import nmap","symbol":"Nmap","correct":"from nmap3 import Nmap"}],"quickstart":{"code":"import nmap3\n\ndef run_nmap_scan(target_host):\n    try:\n        # Initialize nmap3\n        nmap = nmap3.Nmap()\n\n        # Perform a top ports scan (example: scanme.nmap.org is a safe target)\n        print(f\"Scanning top ports on {target_host}...\")\n        results = nmap.scan_top_ports(target_host)\n\n        if results:\n            print(\"Scan results:\")\n            for host, host_data in results.items():\n                if host == 'runtime': continue # Skip runtime metadata\n                print(f\"  Host: {host}\")\n                for port_entry in host_data['ports']:\n                    port_id = port_entry.get('portid')\n                    state = port_entry.get('state')\n                    service = port_entry.get('service', {}).get('name')\n                    product = port_entry.get('service', {}).get('product')\n                    version = port_entry.get('service', {}).get('version')\n                    \n                    port_info = f\"    Port: {port_id}/{port_entry.get('protocol')} State: {state}\"\n                    if service: port_info += f\" Service: {service}\"\n                    if product: port_info += f\" Product: {product}\"\n                    if version: port_info += f\" Version: {version}\"\n                    print(port_info)\n        else:\n            print(\"No results found or host is down.\")\n\n    except nmap3.exceptions.NmapCommandError as e:\n        print(f\"Nmap command error: {e}. Ensure Nmap is installed and in your PATH.\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\n# Replace 'scanme.nmap.org' with your target. \n# DO NOT scan hosts without explicit permission.\nrun_nmap_scan(\"scanme.nmap.org\")","lang":"python","description":"This quickstart initializes the `nmap3.Nmap` class and performs a top ports scan on a specified target. It then prints the host and open port information. Remember to have the Nmap binary installed on your system."},"warnings":[{"fix":"Install the Nmap binary appropriate for your operating system. Ensure its executable path is included in your system's PATH environment variable.","message":"The `python3-nmap` library is a wrapper around the Nmap command-line tool. You MUST install the Nmap binary (e.g., `sudo apt install nmap` on Linux) separately on your system for `python3-nmap` to function. Failure to do so will result in `Nmap program was not found in path` errors.","severity":"breaking","affected_versions":"All versions"},{"fix":"If you installed `python3-nmap`, use `from nmap3 import Nmap`. If you intend to use the older API, install `python-nmap` instead (`pip install python-nmap`).","message":"There are two popular Python Nmap wrapper libraries: `python-nmap` and `python3-nmap`. They have different APIs and import paths (`import nmap` vs. `from nmap3 import Nmap`). Installing `python3-nmap` but using `import nmap` will lead to `AttributeError: module 'nmap' has no attribute 'PortScanner'`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Execute your Python script with `sudo python your_script.py` on Linux/macOS or run your terminal/IDE as an administrator on Windows when performing privileged scans.","message":"Some Nmap scan types, particularly OS detection (`nmap_os_detection`) and certain advanced techniques, require root or administrator privileges to execute successfully. Running your Python script without these privileges will result in failed scans or incomplete results.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the `python3-nmap` documentation for its current API if migrating from `python-nmap`. If using older `python-nmap`, check its changelog for specific breaking changes.","message":"The older `python-nmap` library, which `python3-nmap` is a successor to, underwent significant API changes. For instance, `PortScannerAsync` was removed and `PortScannerYield` was renamed to `iterscan` in `python-nmap` version 0.7.0. While `python3-nmap` is a separate project, be aware that migrating from very old `python-nmap` codebases might involve significant refactoring.","severity":"deprecated","affected_versions":"python-nmap < 0.7.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the Nmap command-line tool for your operating system (e.g., `sudo apt install nmap` on Debian/Ubuntu, `brew install nmap` on macOS, or download from nmap.org for Windows). Ensure the Nmap executable's directory is in your system's PATH.","cause":"The Nmap binary is not installed on your system or is not located in a directory listed in your system's PATH environment variable.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'nmap program was not found in path'"},{"fix":"Verify that the Nmap binary is installed and its location is in your system's PATH. For Windows users, you might need to manually add the Nmap installation directory to your environment variables.","cause":"Similar to the `FileNotFoundError`, this error indicates that the `python-nmap` library (which `python3-nmap` is often confused with) cannot locate the Nmap binary.","error":"('Nmap not found', <class 'nmap.nmap.PortScannerError'>)"},{"fix":"Change your import statement from `import nmap` to `from nmap3 import Nmap` and adapt your code to use the `nmap3` API. If you specifically need the `PortScanner` class, you might need to uninstall `python3-nmap` and install `python-nmap` instead (`pip install python-nmap`).","cause":"You have likely installed `python3-nmap` but are attempting to use the `PortScanner` class from the older `python-nmap` library (which uses `import nmap`). `python3-nmap`'s primary class is `nmap3.Nmap`.","error":"AttributeError: module 'nmap' has no attribute 'PortScanner'"},{"fix":"Ensure `python3-nmap` is installed in your active Python environment: `pip install python3-nmap`. If using a virtual environment, activate it before installing. Verify with `pip show python3-nmap`.","cause":"The `python3-nmap` library, which provides the `nmap3` module, is not installed in your current Python environment. This could be due to a missed installation, a virtual environment issue, or installing the wrong library (e.g., `python-nmap`).","error":"ModuleNotFoundError: No module named 'nmap3'"}]}