impgraph

Visualise the import dependency graph of any Python project or file.

• AST-based parsing — accurate, handles all import forms
• Pure-Python rendering via matplotlib — no system Graphviz required
• Interactive HTML output via pyvis — hover, drag, zoom
• Cycle detection and per-module metrics (in/out-degree, PageRank)
• Rich terminal output with progress spinner and tables

---

Installation

pip install impgraph

No system dependencies required — rendering is done entirely in Python via matplotlib.

To use the pygraphviz backend (requires system Graphviz + brew install graphviz):

pip install "impgraph[pygraphviz]"

---

Quick start

# Print a table of modules and imports (no rendering needed)
impgraph info path/to/project

# Render a PNG dependency graph
impgraph graph path/to/project -o graph.png

# Also write an interactive HTML graph
impgraph graph path/to/project -o graph.png --html

# Show import cycles and per-module metrics
impgraph graph path/to/project --cycles --metrics

---

Commands

impgraph graph <path>

Render the import dependency graph for a file or directory.

Flag	Default	Description
-o / --output	graph.png	Output file path
-f / --format	png	Output format: png, svg, pdf, …
-l / --layout	dot	Graphviz layout: dot, neato, fdp, circo, twopi, …
-j / --json	—	Also write import data as JSON
--html / -H	off	Also write an interactive HTML graph
--stdlib	off	Include standard library imports
--no-relative	off	Exclude relative imports
--pygraphviz	off	Use pygraphviz backend instead of pure-Python graphviz
--cycles	off	Print detected import cycles
--metrics	off	Print per-module in/out-degree and PageRank table

impgraph info <path>

Print a Rich table of every module and its imports. No Graphviz required — useful in CI.

Flag	Default	Description
--stdlib	off	Include standard library imports

---

Visual legend

Colour	Meaning
Blue box	Local module (part of the analysed project)
Green ellipse	External package

---

Notes

• Directories automatically excluded: .venv, venv, __pycache__, .git, dist, build, .mypy_cache, .ruff_cache, node_modules, .vscode, .idea
• Standard library detection uses sys.stdlib_module_names — always accurate for the running interpreter
• A single file can be passed instead of a directory

---

Development

uv sync --all-extras
uv run pytest --cov
uv run mypy src/
uv run ruff check src/ tests/