importy 0.1.0

Visualize Python import graphs

importy

importy is a Python CLI that makes import dependencies visible.

It statically analyzes .py files, builds a dependency graph, highlights architecture risks, and can profile real import startup time.

Why use it

• See what your code actually depends on
• Understand unfamiliar projects faster
• Catch circular dependencies early
• Find refactor hotspots (high fan-out/hub modules)
• Profile import startup cost in milliseconds

Visual preview

Graph mode

╭─ pyimports summary ─╮
│ Files        27     │
│ Imports      132    │
│ Local        41     │
│ Stdlib       28     │
│ Third-party  6      │
│ Unresolved   57     │
╰─────────────────────╯
app\main.py
├── app.api.main (local)
├── app.core.config (local)
├── fastapi (third_party)
└── sentry_sdk (third_party)

Doctor mode

╭──── pyimports doctor ────╮
│ Dependency health report │
╰──────────────────────────╯
High: No local circular dependencies detected
Medium: 57 unresolved imports across 23 files
Info: Most used third-party imports
Suggestion: Files with high dependency fan-out
Architecture: Top directory layers in scan

Installation

pip install importy

For development:

pip install -e .[dev]

Commands

graph

Scan a file or directory and print dependency tree or JSON.

importy graph path/to/file_or_dir
importy graph path/to/dir --format json
importy graph path/to/app --project-root path/to/repo_root

cycles

Detect circular local dependencies.

importy cycles path/to/dir --project-root path/to/repo_root

cycle is also supported as an alias.

doctor

Print a prioritized dependency health report.

importy doctor path/to/dir --project-root path/to/repo_root

why

Find who imports a module.

importy why app.models path/to/dir --project-root path/to/repo_root

time

Profile real import startup cost with Python -X importtime.

importy time path/to/entry.py --top 20

Notes on accuracy

• local / third_party classification depends on interpreter environment.
• Use --project-root for monorepos or nested app layouts.
• time runs real imports and requires target dependencies installed.

Roadmap

• doctor --json for CI integration
• Better local-path resolution in graph tree annotations
• Layering policy checks (example: api -> service -> db)
• Lazy import suggestion mode