Install & Compatibility
Where this runs
tested against v3.16 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.100s · 24.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.096s · 24MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ImportGraph
✓ from grimp import ImportGraph
✗ from grimp.application.ports.import_graph import ImportGraph
Import
✓ from grimp import Import
build_graph
✓ from grimp import build_graph
This quickstart demonstrates how to build an import graph for a sample Python package. It creates a temporary package structure, uses `build_graph_from_path` to analyze its imports, and then queries the resulting graph. The code includes a basic cleanup for the created files.
import os
from grimp.application.usecases import build_graph_from_path
# Create a dummy package structure for demonstration
os.makedirs('my_package/submodule', exist_ok=True)
with open('my_package/__init__.py', 'w') as f: f.write('')
with open('my_package/module_a.py', 'w') as f: f.write('from .module_b import B')
with open('my_package/module_b.py', 'w') as f: f.write('from my_package.submodule import C')
with open('my_package/submodule/__init__.py', 'w') as f: f.write('')
with open('my_package/submodule/module_c.py', 'w') as f: f.write('import os')
# Build the import graph for 'my_package'
package_path = 'my_package'
package_name = 'my_package'
# NOTE: The exact function signature and import path might vary slightly.
# Refer to Grimp's official documentation for the precise quickstart.
try:
graph = build_graph_from_path(package_name, package_path)
print(f"Nodes in graph: {graph.modules()}")
print(f"Direct imports from module_a: {graph.direct_imports_for_module('my_package.module_a')}")
# Cleanup dummy files
import shutil
shutil.rmtree('my_package')
except ImportError as e:
print(f"Could not build graph, ensure grimp is installed and paths are correct: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
gotchaGrimp performs static analysis and may not accurately reflect imports that are dynamically loaded (e.g., using `importlib` or conditional imports based on runtime conditions). Always verify results for complex import patterns.fixManually inspect dynamic import sites or use runtime analysis tools in conjunction with Grimp for a complete picture.
affects: All versions
breakingThe internal API structure, especially module paths for core functions like `build_graph_from_path` or `ImportGraph`, might change between major or even minor versions. Always consult the release notes when upgrading.fixReview the official Grimp documentation and release notes for updated import paths and API changes during upgrades. Update your import statements and method calls accordingly.
affects: Potentially between major and minor releases (e.g., 2.x to 3.x)
gotchaGrimp's analysis relies on the Python environment it's run in. If analyzing code that targets a different Python version or has specific `sys.path` configurations, Grimp might not resolve imports correctly. Ensure your analysis environment matches the target project's setup.fixRun Grimp in a virtual environment configured with the target project's Python version and dependencies. Explicitly set `sys.path` if necessary to include all relevant source roots.
affects: All versions
Upgrade
Version history
3.16latest on PyPI · released Aug 28, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.10 or higher as per PyPI metadata.