depmap

See how your Python modules connect. Catch circular dependencies before they spread.

depmap reads Python source using the standard library AST parser and produces a dependency graph. It never imports or executes the project you point it at.

flowchart LR
  cli["shop.cli"] --> orders["shop.orders"]
  orders --> inventory["shop.inventory"]
  inventory --> orders
  classDef cycle fill:#44252d,stroke:#ff846b,color:#fff
  class orders,inventory cycle

Loading

Run in 30 seconds

Requires Python 3.10 or newer. No packages to install.

Download the standalone depmap.py from Releases, or clone the repository to include the example project and tests:

git clone https://github.com/AliEmami81/depmap.git
cd depmap
python depmap.py examples
python depmap.py examples --format json
python depmap.py examples --format mermaid --output graph.mmd

For your own repository, pass the import root: the directory you would add to PYTHONPATH. Use src/ for a typical src-layout project.

python depmap.py ../your-project/src --output dependencies.md
python depmap.py ../your-project/src --fail-on-cycle

What you get

• Markdown reports with a Mermaid diagram that GitHub can render.
• JSON containing module paths, internal edges, external import names, cyclic groups, and parse errors.
• Relative import resolution, package imports, and namespace-package module discovery.
• Cyclic groups found using an iterative strongly connected component algorithm, including on deep dependency graphs.
• Common environment, cache, and build directories excluded automatically.
• Syntax errors reported without discarding the rest of the graph.

Exit code	Meaning
0	Analysis completed; no failing condition
1	Cyclic group found with --fail-on-cycle
2	Invalid input, unreadable source, parse error, or output error

Parse errors take precedence over the cycle exit code.

Scope and limits

This is a static source dependency map, not a simulation of Python's import machinery. Imports inside functions, conditional branches, and TYPE_CHECKING blocks are included. Dynamic importlib calls, sys.path manipulation, wildcard symbol expansion, and installed-package version resolution are outside its scope. A cyclic group describes source coupling; it does not necessarily mean the application fails at runtime. Self-imports are omitted. Only the chosen import root is analyzed; selecting a monorepo root can combine otherwise separate import environments. For namespace-package imports, concrete matching modules are resolved; namespace containers without __init__.py are not separate graph nodes.

Development

python -m unittest discover -s tests -v

Tests cover nested relative imports, cyclic groups, source encodings, CLI exit codes, syntax errors, and a graph deeper than Python's default recursion limit. Contributions with a small reproducible example are welcome; see CONTRIBUTING.md.

License

MIT. Built by Ali Emami.