---
id: modulegraph2
version: "2.3"
license: MIT
license_treatment: permissive
maintenance: aging
---

# modulegraph2 — A module import dependency graph for Python projects.

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

## What it is and what it does

Modulegraph2 is a library for building and analyzing the dependency graph between Python modules. It performs static analysis on both source code and bytecode to discover which modules import which others, and annotates each dependency with metadata from the import statement itself. The graph also includes information about packages, extensions, and their relationships, with links to distribution metadata for modules installed via pip.

The package is a complete rewrite of an earlier modulegraph project, built from scratch for Python 3 with full test coverage. It's useful for understanding module structure, detecting circular dependencies, or building tools that need to reason about import relationships in a codebase.

Use it for:

- Analyze import dependencies in a Python project to detect circular imports or unused modules.
- Build tooling that needs to understand the module structure of a codebase for refactoring or optimization.
- Generate documentation or visualizations of how modules in a project depend on each other.
- Validate that a package's public API only imports from intended modules.
- Trace which installed distributions provide modules used by a given Python project.

## Worth the install?

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

Modulegraph2 builds and introspects a dependency graph of Python modules using static analysis of source and bytecode, annotating imports with metadata and linking to installed package information.

Yes, if you need to programmatically analyze Python module dependencies. The package is stable, has no known vulnerabilities, installs easily, and supports current Python versions. The aging maintenance status (264 days since last release) is a minor concern for a mature library, but not a blocker unless you need active development or rapid bug fixes.

## Install

pip install modulegraph2
uv add modulegraph2
poetry add modulegraph2

## Installing modulegraph2

Before you install: Low friction installation with a pure-wheel distribution. Maintenance is aging—last release was 264 days ago and the repository shows infrequent recent activity—but the package is marked Production/Stable and supports current Python versions through 3.15.

License in practice: MIT license is permissive; you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install modulegraph2

from modulegraph2 import ModuleGraph

graph = ModuleGraph()
graph.add_module('mypackage')
for node in graph.nodes():
    print(node)

Requires Python 3.10 or later.

Verify before relying:

- Whether the static analysis accurately handles dynamic imports, conditional imports, or complex import patterns in real-world codebases.
- Performance characteristics when analyzing large projects with hundreds or thousands of modules.
- Whether the rewrite from the original modulegraph maintains backward compatibility or introduces breaking changes for existing users.

## Package facts

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

## Tags

python module dependency graph, static import analysis, module dependency introspection, python package dependency mapping, import graph visualization, bytecode dependency analysis, module relationship discovery, dependency-analysis, static-analysis, module-introspection

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