mrkeyoor.comAsk

achillean/shodan-pythontested 10 Nov 2026commit 87a0688

shodan-python review

Our fresh shodan-python CLI run failed before it could show help: the process could not import pkg_resources.

  • README install 3 s
  • README usage failed
0/19passed, run exited non-zero
  • Install 22 s
  • Build 1 s
Dataevaluationupdated 13 Nov 2026
+3stars / 7d

shodan-python is Shodan's official Python library and bundled command-line tool for querying information about Internet-connected devices. It brings Shodan lookups and searches into scripts and existing security tools; the package is named shodan.

Verdict

Our fresh shodan-python CLI run failed before it could show help: the process could not import pkg_resources. Use the official client when Shodan is already your data source and you can own the Python environment and endpoint permissions. Skip it if you need a demonstrated clean CLI setup or free SDK host searches. The earlier source installation passed, but its test command failed with 19 failures and no passes.

shodan-python infographic: query Shodan about Internet-connected devices, plus our test result and who it suits
Tested 13 November 2026: the README command failed. Before that: 10 Nov: 0 of 19 source tests passed; uv install took 3 s.

We ran it

Lab card: what happened when we ran shodan-python
Lab card from our sandbox run
Screenshot of shodan-python (developer.shodan.io)
developer.shodan.io
Install✓ · 22s42 packages · 41 MB
Build✓ · 1s
Tests✗ · 2s0 passed · 19 failed of 19 (pytest)
Known vulns0(pip-audit)
Repo44 files~4,763 lines of source · 0.2 MB · 0 CI workflows · tests dir

Answers from our run

Does shodan-python build from source?

Dependencies installed in 22 seconds (42 packages), and the build succeeded in 1 seconds. We cloned commit 87a0688 into a clean Debian container with 3 CPUs and no project-specific setup.

Do shodan-python's tests pass?

No. The project's own test command finished in 2 seconds and reported 0 passed, 19 failed (pytest).

Does shodan-python have known vulnerabilities in its dependencies?

pip-audit found none in the dependency tree at the time of our run.

Who should not use shodan-python?

Anyone expecting free SDK host lookups and searches: the maintainer said those operations required at least Membership in issue #187.

What are the alternatives to shodan-python?

shodanpy, pysho. Our fresh shodan-python CLI run failed before it could show help: the process could not import pkg_resources.

Setup3/5In our 2026-11-13 run it installed in 3 s, but its own --version and --help commands crashed.Editor’s note: The fresh CLI stopped at a missing pkg_resources import; supported-environment setup was not demonstrated.
Docs4/5The README has an install section (“Quick Start”) and usage in the same section; we did not run its quickstart ourselves.Editor’s note (scored 3/5): Under the visible documentation rubric, README examples and help guides provide a usable path, but query interpretation and endpoint permissions need issue explanations.
Community2/5Last push on 2024-08-05, 3,488 stars and maintainers answered or closed 9 of the 10 most-discussed issues we sampled.Editor’s note: Historical reports and downstream packaging show use, but do not measure present support capacity or response times.
Maturity3/5Latest release 1.28.0 on 2022-07-09 (4 years old), repository created 2010-09-07 and its test suite did not pass in our sandbox (0 of 19 passed).Editor’s note: No authenticated workflow completed in these runs, leaving production reliability and current endpoint compatibility unassessed.

How we score

Who it’s for

Python developers adding Shodan host information to an existing investigation tool.
Analysts who want repeatable exposure searches, exports and summary statistics from a Shodan account.
Teams willing to manage both the Python environment and permissions for their chosen endpoints.

Who it’s NOT for

Anyone expecting free SDK host lookups and searches: the maintainer said those operations required at least Membership in issue #187.
Users needing a demonstrated clean CLI startup: our fresh run failed even when requesting help.
Distribution maintainers requiring every PyPI release to have a matching Git tag: issue #185 records missing tags and tarball workarounds.
Applications treating successful CLI initialization as streaming access: Radar has a separate subscription requirement in issue #74.

Setup reality

Our November 10 source run installed successfully in 22 seconds, recorded 42 dependencies and 41 MB on disk, and built in 1 second. Tests exited 1 in 2 seconds: 0 passed, 19 failed of 19. The failing tail repeatedly names a missing SHODAN-API-KEY file. Pip-audit reported 0 known vulnerabilities.

Useful API calls need a Shodan key and the account permissions for the endpoint. The maintainer's access-denied thread specifies at least Membership for host lookups and searches; the Radar thread describes a separate streaming subscription requirement.

In the separate November 13 CLI run, both shodan --version and shodan --help failed with ModuleNotFoundError for pkg_resources. The source sandbox recorded 3 CPUs and 8 GB RAM, the CLI sandbox 2 CPUs and 4 GB. Both used the python3.12-bookworm image label, which alone proves neither the runtime nor operating-system version.

Our fresh shodan-python CLI run failed before it could show help: the process could not import pkg_resources. Choose this client if you already need Shodan data and can own the Python environment and account permissions. Skip it if you need a clean, demonstrated CLI setup or free host searches. The source installation succeeded in our earlier sandbox, but its test command failed with 19 failures and no passes.

shodan-python is Shodan's official Python library and bundled CLI, and the package name is shodan. It lets your program ask Shodan about Internet-connected devices instead of building a separate HTTP integration. The useful decision is whether that access fits your workflow: a successful package installation, a working command and permission to retrieve data are separate milestones.

What people use shodan-python for

Researchers and blue-team writers report using shodan-python to combine IP intelligence, repeat exposure searches and export results for other tools. These accounts give a better picture of the audience than the length of the feature list.

Who used it What they did Reported outcome
Purushotham.R, a self-described budding security researcher Combined Shodan host lookups with WHOIS, DNS and geolocation in a domain-information CLI Reported a working script and time saved on manual research
JSaxena, writing about blue-team monitoring Used CLI searches, exports and statistical facets Demonstrated repeatable commands, but reported that several requested output fields were missing
DanMcInerney, integrating device-pharmer Added Shodan searches to another security tool Reported that upgrading requests resolved his connection failure
Arch Linux, Gentoo, Alpine and openSUSE maintainers Packaged the client for Linux distributions Reported missing Git tags, with several switching to PyPI source tarballs

Purushotham.R's example explains the appeal well. A domain investigation needs several sources, and the Shodan call contributes the services and ports associated with an IP. The client is one component of that script. For someone already writing Python, combining these results is a more convincing reason to adopt it than opening a terminal merely to repeat a website lookup.

JSaxena's article shows a different audience: an analyst who wants the same exposure question answered repeatedly. Searches feed files, downloaded results feed parsing commands, and facets summarize a set of results. The missing fields matter here. Before making a spreadsheet or alert depend on a column, inspect the output of that exact query and command.

What happened when we ran it

Our November 13 CLI run reached package installation, then both shodan --version and shodan --help exited 1 with a missing pkg_resources import. The run record identifies commit 87a0688d1e5b, the quickstart-cli recipe and a fresh unprivileged container with 2 CPUs, 4 GB RAM, no published ports and no secrets. The recorded image was ghcr.io/astral-sh/uv:python3.12-bookworm.

CLI check Recorded outcome What it tells a new user
Clone Completed The recipe obtained the source
Package selection The recipe selected PyPI shodan 1.31.0 This CLI run used a published package alongside the recorded checkout
shodan --version Exit 1, ModuleNotFoundError: No module named 'pkg_resources' Startup stopped during an import
shodan --help Exit 1, ModuleNotFoundError: No module named 'pkg_resources' Even the help command hit the same startup failure
Usage step Failed: the recipe found no runnable shodan command in the README's usage/examples sections It did not execute a real data lookup
Teardown OK The sandbox cleanup completed

The version finding and help finding identify the same exception. Asking for help should have been the low-commitment way to inspect the tool. Instead, the traceback entered shodan.__main__, tried to import pkg_resources and stopped. That is a concrete startup obstacle in this environment, before any account question could be answered.

The usage failure also needs careful reading. The recipe reported no runnable CLI command in the README's usage/examples sections. The public README does contain Python quick-start calls, an installation section and a link to CLI documentation. The recipe's result describes what it could execute, rather than proving that the project has no usage documentation.

The earlier source harness ran commit 87a0688 on November 10, 2026 with a recorded configuration of 3 CPUs, 8 GB RAM and the same image label. Its results were:

Source harness step Result
Install Succeeded in 22 seconds, 42 dependencies recorded, 41 MB on disk
Build Succeeded in 1 second
Tests Exit 1 in 2 seconds, pytest reported 0 passed and 19 failed of 19
pip-audit 0 known vulnerabilities reported
Repository scan 44 files, about 4,763 source lines, 0.2 MB checked out
Automation and packaging scan 0 CI workflow files, no Dockerfile, tests directory present

The failing test tail repeatedly names FileNotFoundError for SHODAN-API-KEY. It includes invalid-host and invalid-key cases alongside search, facets and trends cases. The immediate finding is a missing credential file in those failures. A failed test with that exception is not evidence that a search returned the wrong answer. Nor does the successful build cancel the separate CLI startup failure.

Where people get stuck: imports, queries and account access

The issue tracker separates several failures that can look like a broken Shodan client: an import collision, a query interpreted differently from the website, and an account denied access. Match the symptom before changing a key or rewriting a query.

Symptom What the source says Action supported by that report
Host lookup or search returns 403 In issue #187, achillean said IP lookups and searches required at least Membership Check the account's entitlement before rotating credentials
Searching a bare IP gives an empty screen In issue #62, the maintainer explained the website adds net: automatically Use shodan host for one IP, or an explicit net: search filter
Module has no Shodan attribute In issue #4, a local script name conflicted with the library Rename the local shodan.py file; the reporter confirmed the fix
Unable to connect to Shodan In issue #22, DanMcInerney confirmed a requests upgrade fixed his case Inspect the HTTP dependency when the same circumstances apply
Unable to parse JSON response In issue #51, mdiviesti said a delay stopped errors while querying the exploit endpoint Investigate request pacing for that workload

The blank-screen case is especially easy to misread. The user searched an IP and expected the website's result. The maintainer explained that unfiltered text searches banner contents, while the website adds a net: filter for an IP. Those are different questions. For a single address, the maintainer recommended shodan host; for a search with selected fields, the explicit filter expresses the intended match.

Issue #4 is the cheaper check to make before changing packages. A file named shodan.py can take the installed library's place during import. The reporter confirmed that changing the name solved the attribute error, and later commenters said the explanation remained useful. That resolution belongs to the import-shadowing case, separate from the pkg_resources exception in our CLI run.

Where volume hurts: request pacing and query credits

Bulk retrieval spends Shodan query credits, and the official download guide shows how to stop a Python cursor after a chosen result limit. Put that limit in the job specification before scheduling recurring collection. An open-ended search loop has different account consequences from a single host lookup.

The official guide recommends the bundled CLI for most downloads. It points Python users to search_cursor() when they need to transform banners during retrieval or avoid a local results file. This is a useful division of work: use an existing download command for an export, and write a Python loop when the destination or transformation requires code.

Request pacing deserves its own error path. In issue #51, mdiviesti was looping over products on a network and querying the exploit endpoint. They reported that adding a slight delay stopped their JSON parsing errors. The maintainer closed the thread as support-related. That account supports checking pacing in a similar loop, rather than treating every JSON exception as the same defect.

For a recurring job, record which endpoint ran, whether retrieval completed and how much output you retained. Keep permission failures distinct from empty searches so an expired or ineligible account cannot silently become a report of no exposure. Those are operating recommendations drawn from the documented failures, not extra capabilities supplied by the wrapper.

Security starts with the package name and the account

The official package is shodan; ReversingLabs' supplied record flags the separate python3-shodan package as malicious and removed. The similar name is a reason to follow the project's own package link rather than search for a supposed Python 3 replacement. The official PyPI listing and the separate package assessment identify different distributions.

Our source harness reported 0 known vulnerabilities from pip-audit. That result concerns known advisories in that run. Package identity and credential handling still need deliberate choices: keep the Shodan key out of committed scripts, screenshots and copied tracebacks, and review what an export contains before sharing it. The README's example uses a placeholder key, which your application needs to replace through its own credential handling.

The account also sets the feature boundary. Membership access for host lookups and searches appears in issue #187. Streaming has a separate subscription requirement in issue #74. A successful initialization message therefore cannot serve as a permission test for every operation your application will expose.

GitHub tags make downstream packaging harder

Linux distribution maintainers reported missing release tags and used PyPI source tarballs as a workaround. In issue #185, Arch Linux and Gentoo maintainers described the source-to-release matching problem. Alpine and openSUSE maintainers described fetching the PyPI tarball instead, and a later comment reported a missing 1.31.0 tag too.

The supplied PyPI record lists shodan 1.31.0, released December 17, 2023. The public GitHub metadata records the last push as August 5, 2024, while the latest GitHub release entry is 1.28.0 from July 9, 2022. Those dates describe different channels. Looking only at GitHub Releases gives a different picture from looking at the package registry, so record the source artifact and version you actually adopt.

Downstream packaging work is concrete use of the project, but it is not proof of production deployments or prompt support. The missing-tags thread contains a practical workaround and an unresolved request for better release bookkeeping. For a team that rebuilds distributions internally, that is a real maintenance cost to weigh alongside the short Python examples.

shodan-python vs InternetDB, the website and smaller wrappers

InternetDB is the maintainer's suggested alternative for free IP lookups, while the Shodan website handles some input interpretation for you. The most useful first comparison is how you want to access Shodan, before choosing a different Python wrapper.

Route Pick it when Evidence behind the choice
Shodan InternetDB You need the free IP lookup route suggested in the access-denied thread Achillean offered it in issue #187
Shodan website You want an interactive search that recognizes a bare IP Issue #62 explains its automatic net: filter
Bundled shodan CLI You want ordinary downloads and file conversion The official download guide recommends the CLI for most purposes
Python with search_cursor() You need transformations during download or direct handling without a local file The same guide identifies those reasons to write Python

shodanpy by simeononsecurity offers another collection of Python modules for the Shodan API. It is a candidate if you want that project's module organization and are prepared to inspect its interfaces. Switching wrappers still leaves you using Shodan's service, so choose it for a specific integration need rather than assuming it changes the account's permissions.

Kr0ff's pysho is a Python tool for querying Shodan. Its README demonstrates account information, keyword searches and IP searches. Consider it if those explicit commands match the tool you want to read or adapt. The official package remains the documented route for the broader SDK and bundled CLI. Neither alternative gets a speed or reliability advantage from the evidence here.

What the other reviews get wrong

SkillFed's dependency-free description conflicts with our recorded dependency installation and a confirmed requests-related failure in the tracker. Its overview describes no runtime dependencies, yet issue #22 documents DanMcInerney resolving a connection problem by upgrading requests. Our source harness recorded 42 dependencies. That environment count is not a declaration of 42 direct runtime requirements, but the blanket dependency-free verdict gives readers the wrong expectation.

SkillFed also makes an active API key the main qualification for adoption. The maintainer's response in issue #187 adds the consequential condition: host lookups and searches required at least Membership in that thread. The reporter had already tried changing keys. A recommendation needs to ask which operation the account can perform, rather than stop at whether a key exists.

These corrections matter more than arguing over a generic quality score. An analyst can follow a package installation instruction correctly and still encounter either the CLI import error we saw or an account denial reported by other users. Each requires a different next check. The SkillFed record is useful as a snapshot of those claims, not as evidence that either requirement has disappeared.

Questions people ask

The GitHub project is achillean/shodan-python, while the installable package is named shodan. The recurring questions concern that naming, account access and differences between the website and CLI.

Where can I find shodan-python on GitHub?

The official repository is achillean/shodan-python. Its README links the Python documentation and Shodan help site. Use the package name shodan when following the official installation instructions.

Why do Shodan host lookups return 403 Forbidden even after I change my API key?

The maintainer said host lookups and searches required at least Membership in issue #187. Changing a key does not change the account's entitlement. Check permission for the operation that failed.

Why does shodan search show a blank screen for an IP that works on the website?

The website automatically adds a net: filter for a bare IP, according to issue #62. The CLI leaves that choice to you. Use the explicit filter for search or shodan host for a single-IP lookup.

How can I fix Unable to parse JSON response errors?

Adding a delay stopped the errors for mdiviesti's exploit-endpoint loop in issue #51. Treat that as a reported remedy for a particular workload. Capture the exact call and exception without exposing the key when investigating another case.

Why does the shodan module have no Shodan attribute?

A local file named shodan.py shadowed the library in issue #4. Renaming the script resolved the reporter's case. Check which file Python imported before replacing the documented Shodan class with an older API name.

Does shodan-python support Python 3?

The maintainer confirmed Python 3 support in issue #6, and the final commenter reported getting it working. That historical answer is separate from our fresh CLI run's missing pkg_resources import.

Why does Radar fail when my other Shodan commands work?

Radar uses the Streaming API, which the maintainer said needed an eligible API subscription in issue #74. The maintainer fixed error handling for the StandardError traceback and small windows, while retaining the access requirement.

Where are the Git tags for releases published on PyPI?

Downstream maintainers reported missing tags in issue #185, including a later report about 1.31.0. Several used PyPI source tarballs instead. Match your chosen package artifact directly rather than assuming a corresponding Git tag exists.

Can free Shodan API access return in the future?

Issue #187 ends with a user asking whether free access will return, without a recorded commitment. The concrete alternative offered by the maintainer was InternetDB for free IP lookups.

Documentation earns a qualified score, not a compatibility promise

Documentation receives 3/5 because the README, help guide and resolved issue explanations provide a usable path, while important query and entitlement distinctions require reading across them. Our editorial scale is 1 for instructions missing an essential path, 3 for a usable path with consequential gaps and 5 for clear coverage of the assessed workflow, with 2 and 4 between those anchors.

Setup, community and maturity are marked unassessed. The observed import failure is useful evidence about one setup, and historical issue resolutions help troubleshoot particular symptoms. They do not support a numerical judgment about supported-platform setup, present support capacity or production reliability. Stars and downstream packages cannot supply those missing assessments.

What we have not tested yet

Our runs do not establish successful authenticated host lookups, searches, streaming, alerts, bulk exports or exploit queries. We have not tested a repaired CLI environment, a modern-Python compatibility matrix, throughput, long-running reliability or the alternative wrappers. The sandbox image label does not establish the actual interpreter or operating-system version; those require raw toolchain logs.

The source harness's missing-file failures do not measure endpoint correctness, and the later CLI run stopped before account initialization. We did not reproduce the historical community fixes. The JSON-delay remedy is case-specific, and the blank-screen thread does not show a shipped feedback fix. Current endpoint entitlements and a complete streaming-plan matrix need a separate account-backed check, without treating historical prices as today's offer.

The researcher's domain-intelligence output is illustrative, rather than independent proof of the reported time saving. Our advisory result is not a security audit or a malware analysis. The pack contains no screenshots or known-answer data tasks. These boundaries leave a clear next adoption check: get the CLI to display help in your intended environment, then run the exact permitted operation your application needs.

Alternatives

ProjectWhat it isPick it when
shodanpyA separate collection of Python modules for the Shodan API.Consider it when you want to inspect or adapt that project's module interfaces for a specific Shodan integration.
pyshoA Python command-oriented tool with examples for account information, keyword searches and IP searches.Consider it when those explicit commands match the small tool you want to read or adapt.

Sources

  1. Official shodan-python repository
  2. Official package listing
  3. Official data download guide
  4. Host and search access issue
  5. CLI query interpretation
  6. Missing release tags

More data reviews