Install & Compatibility
Where this runs
tested against v1.31.0 · 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.619s · 26.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.6s · import 0.572s · 27MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Shodan
✓ from shodan import Shodan
✗ import shodan; api = shodan.Shodan()
While 'import shodan' followed by 'shodan.Shodan()' works, 'from shodan import Shodan' is the idiomatic way to import the main class.
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.
import os
from shodan import Shodan
from shodan.exception import APIError
SHODAN_API_KEY = os.environ.get('SHODAN_API_KEY', 'YOUR_SHODAN_API_KEY')
if not SHODAN_API_KEY or SHODAN_API_KEY == 'YOUR_SHODAN_API_KEY':
print("Please set the SHODAN_API_KEY environment variable or replace 'YOUR_SHODAN_API_KEY'.")
else:
try:
api = Shodan(SHODAN_API_KEY)
# Lookup your current IP address information
my_ip_info = api.tools.myip()
print(f"Your IP: {my_ip_info}")
# Search for servers running Apache
results = api.search('apache')
print(f"Results found for 'apache': {results['total']}")
for result in results['matches']:
print(f" IP: {result['ip_str']}, Port: {result['port']}, Org: {result['org']}")
break # Print only the first result for brevity
# Lookup a specific host (e.g., Google DNS)
host_info = api.host('8.8.8.8')
print(f"\nHost 8.8.8.8 info: {host_info['country_name']}, {host_info['org']}")
except APIError as e:
print(f"Error: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
shodan --version
Errors
Common errors & fixes
AttributeError: 'module' object has no attribute 'Shodan'
A Python script in your working directory is named `shodan.py`, creating a name conflict with the installed `shodan` library.
fixRename your Python script file to something other than `shodan.py` (e.g., `my_shodan_script.py`).
shodan.exception.APIError: Access denied
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).
fixEnsure 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.
shodan.exception.APIError: The search request timed out or your query was invalid. OR shodan.exception.APIError: Unable to parse JSON response
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.
fixVerify 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.
IOError: [Errno 9] Bad file descriptor (when running CLI) OR issues with ANSI escape sequences/colored output.
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.
fixUse 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.
Upgrade
Version history
1.31.0latest on PyPI · released Dec 17, 2023
Audit
Dependencies
requestsrequiredUsed internally for HTTP requests to the Shodan API. Typically installed automatically by pip.