# python-seo-analyzer for Python-Based Site Audits

> python-seo-analyzer crawls sites, inspects page structure, counts body words, and reports technical SEO issues through a Python CLI. It fits small HTML sites and developer workflows, while the README recommends another tool for larger crawling workloads.

**sethblack/python-seo-analyzer** — An SEO tool that analyzes the structure of a site, crawls the site, count words in the body of the site and warns of any technical SEO issues.

- Repository: https://github.com/sethblack/python-seo-analyzer
- Stars: 1,489 · Forks: 351
- Language: Python
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/sethblack-python-seo-analyzer

## What python-seo-analyzer Checks

python-seo-analyzer addresses a specific task: inspecting a website's crawlable structure and basic SEO signals from the command line. Its project description names site-structure analysis, crawling, body-word counting, and warnings about technical SEO issues. That makes it relevant to developers, small website operators, and teams that want a repeatable audit command rather than a separate web interface.

The README says the author created it around 2010 to crawl small, HTML-only websites. It now also describes analysis of content signals associated with search and AI search, including expertise signals, conversational engagement, and cross-platform presence. Those AI-related checks are separate from the ordinary crawl. They require `--run-llm-analysis` and a key for the selected external provider.

The documented scope does not extend into search-console reporting, backlink research, keyword planning, or search-result ranking. It starts with a URL or sitemap and analyzes the fetched pages. The project examines the site itself and the structure and content visible to its crawler. It should not be confused with a complete replacement for professional search analysis, because the README does not document competitor analysis, search-console data, or continuous rank tracking.

## Crawling, Parsing, and Report Generation

According to the README, running the command without a sitemap starts crawling at the homepage. Supplying a sitemap seeds the scan with an explicit URL list. This distinction affects audit coverage. A homepage crawl discovers pages through links encountered by the crawler, while a sitemap lets the operator provide a known page inventory.

The dependencies reveal much of the implementation stack. BeautifulSoup and lxml provide the HTML-processing foundation, while trafilatura is included for readable body extraction. That is relevant to word counting because extracting only the main article can produce a different count from counting every string in the raw HTML response. Jinja2 and MarkupSafe support templated output, including the documented HTML report.

The README does not document crawl-depth limits, concurrency controls, robots.txt handling, retry policy, redirect treatment, or JavaScript execution. Based on the repository layout and Python dependencies, it is a conventional Python crawler and parser rather than a documented headless-browser system. Auditors should therefore inspect whether content generated after client-side JavaScript execution appears in the pages fetched by this tool.

The CLI emits JSON by default and can produce an HTML report through `--output-format html`. A report is useful for sharing findings, but the README does not publish a complete warning catalogue, severity model, or scoring rubric. A finding's operational importance may require human review rather than direct interpretation as a pass or fail result.

## Installing the Python CLI Safely

For a conventional Python environment, the README gives the package name `pyseoanalyzer` and the console command `python-seo-analyzer`. Creating a virtual environment prevents the installation from modifying a system or externally managed Python environment:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install pyseoanalyzer
```

After activation, the documented entry point accepts a target URL:

```bash
python-seo-analyzer http://www.domain.com/
```

The repository's `pyproject.toml` declares Python 3.8 or later. It defines the `python-seo-analyzer` console script through the `pyseoanalyzer.__main__:main` entry point. The README also documents `seoanalyze` in one HTML-output Docker example, although the primary installation section consistently names `python-seo-analyzer` as the command placed on `PATH`.

On macOS with Homebrew, the README specifically addresses the `error: externally-managed-environment` result associated with PEP 668. It recommends pipx so that the package receives its own environment:

```bash
brew install pipx
pipx ensurepath
pipx install pyseoanalyzer
```

After pipx installation, the documented crawl command remains:

```bash
python-seo-analyzer http://www.domain.com/
```

No virtual environment activation is needed for that installation. The README does not provide equivalent pipx instructions for Windows, so the macOS sequence should not be treated as a universal package-management workflow.

## Running a Docker Audit with HTML Output

The repository includes a Dockerfile based on `python:3.13.2-bookworm`. Its build installs dependencies from `requirements.txt`, installs the local project, creates a non-root user, and sets `python-seo-analyzer` as the image entry point. The README identifies the published Docker Hub image as `sethblack/python-seo-analyzer:latest`.

A basic container invocation is:

```bash
docker pull sethblack/python-seo-analyzer:latest
docker run --rm sethblack/python-seo-analyzer http://example.com/
```

The default output is JSON. For a shareable HTML result, the README documents `--output-format html`. To save that report locally, it shows a volume mounted at `/app/output` and shell redirection to `results.html`:

```bash
docker run --rm -v "$(pwd):/app/output" sethblack/python-seo-analyzer /bin/sh -c "seoanalyze http://example.com/ --output-format html > /app/output/results.html"
```

The command uses `$(pwd)`. The README supplies separate substitutions for Windows CMD and PowerShell rather than one syntax that works in every shell.

A local sitemap can also be mounted into the container. Its path inside the container becomes part of the analyzer command:

```bash
docker run --rm -v "$(pwd)/local-sitemap.xml:/app/sitemap.xml" sethblack/python-seo-analyzer http://example.com/ --sitemap /app/sitemap.xml
```

This approach is appropriate when Docker is already part of the operating environment and the audit should run without activating a host virtual environment. The image runs as `appuser`, which is relevant when mounted files and generated output must be writable by that account.

## Optional Anthropic and OrcaRouter Analysis

The AI mode evaluates content characteristics that the README associates with AI search. Named areas include expertise signals, conversational engagement, and cross-platform presence. The README says this design was influenced by a Search Engine Land article, but it does not publish the prompt, model name, scoring thresholds, or decision rules used by the implementation.

The activation contract is clearer than the scoring model. Anthropic access requires `ANTHROPIC_API_KEY`:

```bash
docker run --rm -e ANTHROPIC_API_KEY="your_api_key_here" sethblack/python-seo-analyzer http://example.com/ --run-llm-analysis
```

The README also documents OrcaRouter through `ORCAROUTER_API_KEY`:

```bash
docker run --rm -e ORCAROUTER_API_KEY="your_api_key_here" sethblack/python-seo-analyzer http://example.com/ --run-llm-analysis
```

These examples pass a key into a disposable container. The README does not document model selection, request limits, costs, retries, timeouts, or the site content sent to either service. Operators should not enable this mode until those points are confirmed for their own environment.

The output should also be treated as advisory. The README does not claim that the analysis directly predicts search-engine rankings or proves that a page will perform better in AI results. Its practical value is as a second review layer over crawled content. A finding still needs to be checked against the page's purpose and the limitations of the crawler.

## Scale Limits and Incomplete Crawl Risk

The most explicit limitation comes from the author. The README says Python is not always suitable for website crawling, describes Python SEO Analyzer as acceptable for most smaller use cases, and points readers who need a faster and more comprehensive tool to Black SEO Analyzer. That boundary matters for large websites, high crawl volumes, and jobs with strict completion times.

The project is also oriented toward HTML-only sites. The README does not confirm JavaScript rendering, authenticated crawling, personalization handling, or access to pages behind login forms. A site that loads its main content after client-side execution can therefore produce a partial or misleading audit unless the command still receives the required HTML and readable text.

Crawl failures can also limit coverage. The README does not explain how redirects, unavailable pages, timeouts, blocked requests, duplicate URLs, or authentication failures affect the final report. Operators should compare discovered or submitted URLs with the pages represented in the output. A clean-looking report is only useful if the expected pages were actually examined.

For these reasons, python-seo-analyzer is the wrong tool when browser execution or high-volume crawling is a firm requirement. It is more appropriate when the relevant content is present in crawlable HTML and the goal is a repeatable technical audit of a comparatively small site.

## Black SEO Analyzer and the Project's Upgrade Burden

The README names Black SEO Analyzer as the alternative for users seeking faster and more comprehensive crawling. The difference is stated clearly enough to affect selection: python-seo-analyzer is the Python package with a documented CLI, Docker image, and optional external-provider analysis, while the author recommends Black SEO Analyzer when crawl speed and broader scope matter.

The repository is not archived, and the last push was on 2026-10-08. Recent release entries include `2025.4.3` on 2025-04-03, `2024.04.21` on 2024-04-21, and `4.0.6` on 2022-01-16. The release history changes format across versions, and the README does not provide migration instructions for those upgrades.

`pyproject.toml` pins dependencies including `beautifulsoup4==4.13.3`, `lxml==6.1.0`, `trafilatura==2.0.0`, `langchain==0.3.30`, and `langchain-anthropic==1.4.6`. Teams rebuilding the Docker image should review both `pyproject.toml` and `requirements.txt` because the test dependencies in `requirements.txt` differ from the runtime dependency list in `pyproject.toml`.

The license metadata is inconsistent enough to require direct review. The project description calls it a custom license that GitHub cannot classify, while `pyproject.toml` includes an OSI-approved BSD license classifier and points to `LICENSE`. The README does not reproduce the terms. Review that file before redistributing modified versions or incorporating the tool into a commercial service.

## Conclusion

Adopt python-seo-analyzer for small HTML sites, local audits, and developer workflows that benefit from a Python CLI and optional AI analysis. Do not choose it for large-scale crawling without first reviewing the author's stated workload boundary. Verify crawl coverage, the actual meaning of its warnings, the behavior of JavaScript-dependent pages, and the permissions in LICENSE before production adoption.

## FAQ

### How do I install python-seo-analyzer?

The README documents `pip install pyseoanalyzer` in a Python environment and recommends `pipx install pyseoanalyzer` on macOS with Homebrew. It also publishes the Docker image `sethblack/python-seo-analyzer:latest`.

### What command starts a python-seo-analyzer crawl without a sitemap?

The documented command is `python-seo-analyzer http://www.domain.com/`. The README says a crawl without `--sitemap` starts from the homepage.

### How do I enable AI analysis in python-seo-analyzer?

Add `--run-llm-analysis` and provide either `ANTHROPIC_API_KEY` or `ORCAROUTER_API_KEY`. The README does not document the underlying prompt, model, or scoring thresholds.

### Is python-seo-analyzer suitable for large websites?

The README describes it as acceptable for most smaller use cases. It points to Black SEO Analyzer when readers need faster and more comprehensive crawling, so large-scale suitability should be verified first.

### Can python-seo-analyzer produce an HTML report?

Pass `--output-format html`. The README also shows a Docker invocation that redirects the HTML output to `results.html` through a mounted output directory.

## Sources

- [Issues](https://github.com/sethblack/python-seo-analyzer/issues)
- [README](https://github.com/sethblack/python-seo-analyzer/blob/main/README.md)
- [Releases](https://github.com/sethblack/python-seo-analyzer/releases)
- [sethblack/python-seo-analyzer on GitHub](https://github.com/sethblack/python-seo-analyzer)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sethblack-python-seo-analyzer