{"id":7715,"library":"shodan","title":"Shodan Python Library","description":"The Shodan Python library provides a comprehensive wrapper around the Shodan REST API and the experimental Streaming API, allowing developers to programmatically access information about Internet-connected devices, search for exploits, perform bulk IP lookups, and consume real-time Shodan data. Version 1.31.0 is the latest release, with updates released periodically to add new features and handle API changes.","status":"active","version":"1.31.0","language":"en","source_language":"en","source_url":"https://github.com/achillean/shodan-python","tags":["security","network-scanning","api-client","shodan","iot","cybersecurity"],"install":[{"cmd":"pip install shodan","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used internally for HTTP requests to the Shodan API. Typically installed automatically by pip.","package":"requests","optional":false}],"imports":[{"note":"While 'import shodan' followed by 'shodan.Shodan()' works, 'from shodan import Shodan' is the idiomatic way to import the main class.","wrong":"import shodan; api = shodan.Shodan()","symbol":"Shodan","correct":"from shodan import Shodan"}],"quickstart":{"code":"import os\nfrom shodan import Shodan\nfrom shodan.exception import APIError\n\nSHODAN_API_KEY = os.environ.get('SHODAN_API_KEY', 'YOUR_SHODAN_API_KEY')\n\nif not SHODAN_API_KEY or SHODAN_API_KEY == 'YOUR_SHODAN_API_KEY':\n    print(\"Please set the SHODAN_API_KEY environment variable or replace 'YOUR_SHODAN_API_KEY'.\")\nelse:\n    try:\n        api = Shodan(SHODAN_API_KEY)\n\n        # Lookup your current IP address information\n        my_ip_info = api.tools.myip()\n        print(f\"Your IP: {my_ip_info}\")\n\n        # Search for servers running Apache\n        results = api.search('apache')\n        print(f\"Results found for 'apache': {results['total']}\")\n        for result in results['matches']:\n            print(f\"  IP: {result['ip_str']}, Port: {result['port']}, Org: {result['org']}\")\n            break # Print only the first result for brevity\n\n        # Lookup a specific host (e.g., Google DNS)\n        host_info = api.host('8.8.8.8')\n        print(f\"\\nHost 8.8.8.8 info: {host_info['country_name']}, {host_info['org']}\")\n\n    except APIError as e:\n        print(f\"Error: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This quickstart initializes the Shodan API client using an API key (preferably from an environment variable), retrieves the user's IP, performs a basic search for 'apache' servers, and looks up information for a specific IP address. It includes basic error handling for API-specific exceptions."},"warnings":[{"fix":"Always use `pip install shodan` for installation and upgrades.","message":"Older documentation and examples may suggest installing with `easy_install`. This method is deprecated and `pip` should be used instead.","severity":"deprecated","affected_versions":"<1.20.0 (docs)"},{"fix":"Review Shodan's pricing and upgrade your API plan if needed to access restricted features.","message":"Access to certain advanced features (e.g., Streaming API, Shodan Monitor vulnerability whitelisting, custom data streams, Bulk Data API) requires a paid Shodan API plan. A free developer API key will result in 'Access denied' errors for these features.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement proper error handling with exponential backoff for retries, or introduce delays between successive API calls, especially in loops.","message":"The Shodan API implements rate limiting, typically allowing 1 request per second with some bursting. Exceeding this limit will cause `APIError` exceptions.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Rename your Python script file to something other than `shodan.py` (e.g., `my_shodan_script.py`).","cause":"A Python script in your working directory is named `shodan.py`, creating a name conflict with the installed `shodan` library.","error":"AttributeError: 'module' object has no attribute 'Shodan'"},{"fix":"Ensure your Shodan API key is correct and has an active subscription plan that includes access to the specific API feature you are trying to use. Check your Shodan account settings.","cause":"The API key provided does not have the necessary permissions or subscription level to access the requested Shodan resource (e.g., Streaming API, Bulk Data API, Shodan Monitor).","error":"shodan.exception.APIError: Access denied"},{"fix":"Verify your search query against Shodan's documentation. If performing multiple requests, implement rate-limiting or exponential backoff. Check the Shodan status page for service outages.","cause":"This error can stem from several issues: exceeding API rate limits, providing an improperly formatted or invalid search query, or encountering temporary API service issues.","error":"shodan.exception.APIError: The search request timed out or your query was invalid. OR shodan.exception.APIError: Unable to parse JSON response"},{"fix":"Use a more modern terminal application like Windows Terminal, PowerShell, or a compatible Linux/macOS terminal. Ensure the `colorama` library (a dependency for CLI color support) is correctly installed in your environment.","cause":"This typically occurs when running the `shodan` command-line interface in older Windows Command Prompt environments that lack full support for ANSI escape sequences used for colored output.","error":"IOError: [Errno 9] Bad file descriptor (when running CLI) OR issues with ANSI escape sequences/colored output."}]}