py-import-graph 🕸️

Map every import dependency in a Python project and catch circular imports — using only Python's standard library.

py-import-graph performs AST-based static analysis on your entire Python project, building a complete directed dependency graph and running cycle detection to surface circular imports before they crash your app at runtime.

Why it's useful

• Circular imports cause ImportError or subtle attribute errors that are hard to debug
• Large codebases accumulate tangled imports over time without anyone noticing
• No existing stdlib tool gives you a project-wide dependency map and cycle detector in one command

Features

• 🌐 Project-wide analysis — walks all .py files recursively
• 🔁 Cycle detection — DFS-based, finds all circular import chains
• 🌳 ASCII dependency tree — visual tree of who imports what
• 📊 Most-imported ranking — shows your most-depended-on modules
• 🎨 Graphviz DOT export — render with dot -Tsvg graph.dot > graph.svg
• 🤖 JSON output — pipe into CI scripts or dashboards
• 🏃 Zero dependencies — pure Python stdlib

Installation

git clone https://github.com/sushii15/py-import-graph
cd py-import-graph
# No pip install needed!

Requires Python 3.10+.

Usage

python import_graph.py <project_path> [options]

Options

Flag	Description
--dot	Output Graphviz DOT format
--show-all	Include stdlib & third-party imports
--cycles-only	Print only circular import chains
--json	Machine-readable JSON summary

Examples

# Full report for current directory
python import_graph.py .

# Check for circular imports in a project
python import_graph.py /path/to/project --cycles-only

# Export to Graphviz (requires graphviz installed separately)
python import_graph.py . --dot > graph.dot
dot -Tsvg graph.dot > graph.svg

# JSON output for CI
python import_graph.py . --json | jq '.circular_imports'

Example Output

🔍 py-import-graph  ·  myproject
══════════════════════════════════════════════════════
  Modules analysed : 12
  Import edges     : 18

  Most-imported modules:
     5×  utils
     3×  models
     2×  config

  ⚠️  Circular imports : 1
    [1] auth → session → auth

📊 Dependency Tree:
📦 app
  ├── models
  │   └── utils
  └── auth
      └── session ♻

📦 cli
  └── config

How it works

1. Recursively scans *.py files (skipping .venv, __pycache__, etc.)
2. Parses each file with Python's ast module to extract import and from ... import statements
3. Resolves relative imports (.models, ..utils) to absolute module names
4. Builds a directed graph: module → {set of imported modules}
5. Filters to project-internal modules by default (no stdlib noise)
6. Runs depth-first search to enumerate all strongly-connected components (cycles)

Running Tests

python test_import_graph.py -v

Tests use only tempfile and stdlib — no fixtures or extra setup required.

Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit: git commit -m 'feat: add your feature'
4. Push and open a PR

License

MIT License — see LICENSE for details.