---
id: modulegraph
version: "0.19.7"
license: MIT
license_treatment: permissive
maintenance: aging
---

# modulegraph — Python module dependency analysis tool

License: permissive · Maintenance: aging · Downloads: 114.9K/mo

## What it is and what it does

modulegraph is a Python module dependency analyzer that uses bytecode examination and AST parsing to determine which modules import which others, producing a directed graph of dependencies. It extends the standard library's modulefinder with more flexible internal representation, better handling of edge cases (namespace packages, invalid modules, relative imports), and extensibility for custom analysis.

The package is primarily used as a building block in tools that need to understand Python module structure—most notably py2app for creating standalone macOS applications. It handles modern Python versions through 3.14 and maintains backward compatibility with Python 2.7, though recent releases focus on contemporary Python support.

Use it for:

- Build tools that need to trace which modules a Python script depends on to bundle or freeze applications.
- Static analysis tools that visualize or report on module dependency graphs within a codebase.
- Linters or auditors checking for circular imports or unintended cross-module dependencies.
- Packaging tools determining which modules to include when distributing a Python application.
- Development environments generating module dependency documentation or diagrams.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

modulegraph analyzes Python module dependencies by examining bytecode and import statements, building a directed graph of which modules depend on which others.

Yes, if you need module dependency analysis for build automation or static analysis. The low install friction, permissive license, and lack of known vulnerabilities make it safe to add. However, the aging maintenance status (265 days since last release) and focus on legacy py2app use suggest it is stable but not actively evolving; verify it meets your specific Python version and analysis requirements before relying on it for new tooling.

## Install

pip install modulegraph
uv add modulegraph
poetry add modulegraph

## Installing modulegraph

Before you install: Low friction installation with only two runtime dependencies (altgraph and setuptools). Maintenance status is aging—last release 265 days ago—but the repository remains active with recent commits and no archived status.

License in practice: MIT license permits unrestricted use, modification, and distribution in both open-source and proprietary projects with minimal obligations.

Quickstart:

pip install modulegraph

from modulegraph.modulegraph import ModuleGraph

mg = ModuleGraph()
mg.import_hook('mymodule')
print(mg.nodes())

Verify before relying:

- Whether Python 2.7 support is actively maintained or deprecated in practice despite classifier presence.
- Current state of Python 3.13 and 3.14 support maturity given recent addition in 0.19.7.
- Whether the package is suitable for production use in modern Python tooling or primarily maintained for legacy py2app compatibility.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 114.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

python module dependency analysis, import graph analysis, bytecode import scanning, module dependency visualization, python import tracing, static module analysis, dependency graph builder, dependency-analysis, bytecode-inspection, graph-building

[View on SkillFed](https://skillfed.io/packages/modulegraph) · [View on PyPI](https://pypi.org/project/modulegraph/)