AST-Based Analysis
Pure static analysis using Python's Abstract Syntax Tree. No code execution, completely safe for any codebase.
A deterministic, AST-verified call graph for any Python project — every edge traceable to a file:line. The reproducible, CI-gateable alternative to LLM-generated diagrams. No code executed. Nothing leaves your machine.
pip install py-code-visualizer
From quick analysis to deep architectural insights, PyVisualizer has you covered.
Pure static analysis using Python's Abstract Syntax Tree. No code execution, completely safe for any codebase.
Track function and method calls across modules. See exactly how your code connects and flows.
Force-directed graphs with search, filter, zoom, pan, and dark mode. All in a single HTML file.
Generate diagrams that render natively in GitHub, GitLab, VS Code, and any Mermaid viewer.
Focus on specific modules, exclude tests, limit call depth, and control graph size for large codebases.
Auto-update diagrams on every push with included GitHub Actions workflows.
Interactive Mermaid diagram of PyVisualizer's architecture — just like what you'll generate!
flowchart TD
subgraph CLI["CLI Layer"]
main["main()"]
parse["parse_args()"]
end
subgraph Core["⚙️ Core Analysis"]
analyze["analyze_project()"]
discover["discover_files()"]
ModuleAnalyzer["ModuleAnalyzer"]
ImportCollector["ImportCollector"]
end
subgraph Graph["Graph Building"]
build["build_call_graph()"]
GraphBuilder["GraphBuilder"]
resolve["resolve_calls()"]
end
subgraph Visualizers["Visualizers"]
d3["generate_d3_html()"]
mermaid["generate_mermaid()"]
svg["generate_svg()"]
end
subgraph Output["Output"]
html["architecture.html"]
mmd["architecture.mmd"]
image["architecture.svg/png"]
end
main --> parse
main --> analyze
analyze --> discover
analyze --> ModuleAnalyzer
ModuleAnalyzer --> ImportCollector
analyze --> build
build --> GraphBuilder
GraphBuilder --> resolve
build --> d3
build --> mermaid
build --> svg
d3 --> html
mermaid --> mmd
svg --> image
style CLI fill:#0C3E2F,stroke:#0C3E2F,color:#fff
style Core fill:#14624A,stroke:#0C3E2F,color:#fff
style Graph fill:#1C8462,stroke:#14624A,color:#fff
style Visualizers fill:#275E6E,stroke:#1B4351,color:#fff
style Output fill:#3B8095,stroke:#275E6E,color:#fff
Install from PyPI and generate your first diagram
pip install py-code-visualizer
py-code-visualizer visualize . -o architecture.html
py-code-visualizer readme .
See how PyVisualizer compares to other Python visualization tools
| Feature | PyVisualizer | Pydeps | Pyreverse |
|---|---|---|---|
| Primary Focus | Function Call Graphs | Module Dependencies | UML Class Diagrams |
| Interactive Visualization | ✓ D3.js with search, filter, zoom | ✗ Static images only | ✗ Static images only |
| GitHub-Native Diagrams | ✓ Mermaid support | ✗ | ✓ Mermaid support |
| Function-Level Detail | ✓ | ✗ | ✓ (Classes only) |
| Dark Mode | ✓ | ✗ | ✗ |
| CI/CD Integration | ✓ Included workflows | Manual setup | Manual setup |
| Output Formats | HTML, Mermaid, SVG, PNG | SVG, PNG | DOT, PNG, SVG, PlantUML |
PyVisualizer: Understanding function flow, interactive exploration, onboarding engineers
Pydeps: High-level module dependency mapping
Pyreverse: UML documentation, class inheritance visualization
This tool exists to make code review faster and to give AI agents verified context. Every walkthrough is backed by a runnable fixture — nothing staged.
Turn a big diff into a focused map: what changed, the blast radius, risk flags, and a clickable
file:line on every reference — posted right in the PR.
review --baseinit --with reviewA verified, task-scoped context pack — 97% fewer tokens than the whole repo, zero guessed edges — plus AGENTS.md wiring so agents actually use it.
context --focusexport --for-aiInherit an undocumented codebase and get a trustworthy map, a health grade, and a dead-code review list — in three commands, no code executed.
visualizehealthcheck --dead-codeTurn a layering policy into an enforced, call-graph-level control that fails CI with an exact
file:line, and commit deterministic diagrams as dated evidence.
check --layers --forbidvisualizeMeasure a change's blast radius before you make it, then fail the PR when a refactor quietly introduces a new circular dependency.
impactdiff --fail-on-new-cyclesBackend, API, or ML — the call graph is the same ground truth, shaped to how your project is actually laid out.
See the real request flow — urls → views → services → models — not just the model schema
graph_models draws.
Every route's blast radius through services and repos — async and decorators handled statically, cycles gated in CI.
Map ingest → features → train → evaluate, and find the abandoned experiment code nothing calls anymore.
Every figure below comes from a committed benchmark script you can re-run. No hand-typed metrics.
file:line — provenance on every arrowToken measurements ran on the httpx codebase (1,076 functions, real closed bug) using py-code-visualizer context --task. Speed benchmark: macOS (arm64), Python 3.14, commit 79c3900, on a deterministic
synthetic project (seed 1998). Speed is hardware-dependent — reproduce it yourself with
python benchmarks/bench.py, which writes benchmarks.json.
Provenance, zero-network, and byte-determinism are structural guarantees, not benchmark luck.
Deterministic ground truth an LLM can trust — served openly, no cloaking, no bait.
AI coding agents (Cursor, Claude, Copilot, and autonomous RAG crawlers) re-derive a project's
architecture from raw source and routinely hallucinate the result. py-code-visualizer
gives them a verified alternative:
py-code-visualizer export --for-ai . emits ARCHITECTURE.json +
ARCHITECTURE.md — a call graph with file:line provenance on every edge.pip install py-code-visualizer and run
py-code-visualizer visualize . to generate a self-contained interactive HTML map of
your project's call graph. It uses AST static analysis, so no code is executed.ast module.
Nothing is imported or executed, and the interactive HTML output makes zero network requests, so
it is safe for any codebase and works air-gapped.py-code-visualizer readme injects or updates a Mermaid
diagram between marker comments in any Markdown file. Because output is deterministic, a CI job
only commits when the architecture actually changed — no phantom diffs.py-code-visualizer check --fail-on-cycles exits non-zero on
circular dependencies, and layering rules declared in pyproject.toml are enforced at
call-graph level. py-code-visualizer diff reports newly introduced cycles between
two snapshots.py-code-visualizer visualize <project> -o map.html for an
interactive map, health for an A–F grade, and check --dead-code for a
list of unreachable functions — no code executed, every edge traceable to a
file:line. Full walkthrough:
the orphan monolith.check --layers api domain infra --forbid 'domain -> api' — and the gate fails CI
with the exact file:line. Deterministic committed diagrams make git history a dated
audit trail, and the single-file HTML makes zero network requests (air-gap safe). Full
walkthrough: the audit deadline.py-code-visualizer impact <function> <project> reports
transitive callers/callees and the modules they span. Snapshot the graph before and after and run
diff base.json head.json --fail-on-new-cycles to fail a PR that introduces a cycle.
Full walkthrough: the fearless refactor.py-code-visualizer review . --base origin/main turns the diff into a
focused map — changed functions, blast radius, risk flags (hubs, new cycles, ambiguous calls), and
a changed-neighborhood diagram — with a clickable file:line on every reference.
init --with review posts it as a PR comment automatically. Full walkthrough:
review a PR in minutes.py-code-visualizer context . --focus <fn> builds a task-scoped pack
(97% fewer tokens than the whole source on a real project, zero guessed edges), and
export --for-ai wires AGENTS.md so Copilot/Cursor/Claude consume the
verified graph. Full walkthrough: feed your agent the right
context.Get started in seconds with a single command
pip install py-code-visualizer