Skip to content

Structural static analysis for Python

pyscn

pyscn reads Python the way a compiler does — control-flow graphs, syntax trees, import graphs — to catch what line-by-line linters miss: dead code stranded after a return, logic duplicated under a different name, and modules wired into silent cycles.

uvx pyscn@latest analyze .

Get started View on GitHub

Go binary · zero Python runtime deps · 100,000+ lines/sec · 33 rules

Control-flow graph for a function with unreachable code After the conditional, both branches return. A logging call written after the conditional is never reached, so pyscn flags it as unreachable-after-return. def process(x): if x is None: True return None False return compute(x) ✕ log("done") → flagged: unreachable-after-return

What it finds

  • Unreachable code

    CFG-based reachability finds dead code stranded after return, raise, break, continue, or an always-true branch.

  • Duplicate code

    APTED tree-edit distance plus LSH catches four clone types: identical, renamed, modified, and semantic.

  • Complexity

    Cyclomatic complexity per function, with thresholds you tune per project.

  • Class design

    CBO coupling and LCOM4 cohesion metrics surface classes doing too much, or too little, together.

  • Circular imports

    Tarjan's SCC algorithm finds import cycles before they turn into an ImportError at runtime.

  • Module structure

    Leiden clustering over the import graph shows which modules actually belong together — and which don't.

Install

uvx pyscn@latest analyze .

Runs the latest release without installing anything.

uv tool install pyscn

pipx install pyscn

pip install pyscn

See Installation for all options.

Quick start

pyscn analyze .                                  # full analysis, HTML report
pyscn check --select complexity,deadcode src/    # CI gate
pyscn init                                       # generate .pyscn.toml

See Quick Start and the rule catalog.

AI agent integration

uvx add-skills ludo-technologies/pyscn

Installs Agent Skills that teach Claude Code, Cursor, Codex, Gemini CLI, and other coding agents when and how to run each analysis. See Agent Skills, or use the MCP server for structured tool calls instead.