import-deps

0.5.1 · active · verified Sat Apr 11

import-deps is a Python library and CLI tool designed to find and analyze import dependencies within Python modules and packages. It helps identify issues like circular dependencies, re-imports, and inner imports. It is built upon Python's standard `ast` module, ensuring that analyzed modules are not executed. The library is actively maintained, with version 0.5.1 released in January 2026, indicating a regular release cadence.

Warnings

breaking Dropped support for Python 3.8 and 3.9 in version 0.4.0. Users on these Python versions must use an older version of `import-deps`.
Fix: Upgrade to Python 3.10+ or pin `import-deps<0.4.0` in your project dependencies.
breaking The `--check` CLI flag behavior was unified and changed in version 0.5.0. Previously, it might have had a default check, but now it supports optional types like `--check=all`, `--check=circular`, `--check=reimports`, or `--check=inner`. The behavior of a bare `--check` flag might be different from prior versions.
Fix: Review scripts using `import_deps --check` and explicitly specify the check type, e.g., `import_deps --check=all` for all checks, or `import_deps <path> --check` (without a type before the path) which implies `--check=all`.
gotcha When using `--check=reimports`, `__init__.py` files are explicitly whitelisted by default, as they commonly re-export symbols for a cleaner public API. This means re-imports in `__init__.py` files will not trigger a check failure.
Fix: Be aware of this specific behavior. If strict re-import checks are needed for `__init__.py` files, custom tooling would be required or a different approach to package structure.
gotcha Version 0.5.0 added support for analyzing multiple paths (files and/or directories) in a single command. Older versions might have handled single paths differently or lacked this flexibility.
Fix: When migrating from older versions or designing new analysis, leverage the ability to pass multiple paths to `import_deps` directly for comprehensive analysis, e.g., `import_deps path/to/file.py path/to/dir/`

Install

pip install import-deps Install latest version

Imports

ModuleSet
```
from import_deps import ModuleSet
```
Used for higher-level package dependency analysis.
ast_imports
```
from import_deps.analyzer import ast_imports
```
Used for low-level AST-based import extraction from a single file path.

Quickstart

This quickstart demonstrates basic CLI usage of `import-deps` to analyze a Python package directory and output its dependencies in JSON format. It creates a temporary package structure, runs the `import_deps` command, and prints the result.

import os
import pathlib
import subprocess

# Create a dummy package for demonstration
package_dir = "my_dummy_package"
os.makedirs(f"{package_dir}/sub_module", exist_ok=True)

with open(f"{package_dir}/__init__.py", "w") as f:
    f.write("from .module_a import func_a\n")

with open(f"{package_dir}/module_a.py", "w") as f:
    f.write("import os\nfrom .sub_module.module_b import func_b\ndef func_a(): pass\n")

with open(f"{package_dir}/sub_module/module_b.py", "w") as f:
    f.write("import sys\ndef func_b(): pass\n")

# Run import-deps CLI to analyze the package and output JSON
print(f"\nAnalyzing '{package_dir}' with import-deps CLI:\n")
cmd = ["import_deps", package_dir, "--json"]
result = subprocess.run(cmd, capture_output=True, text=True, check=True)
print(result.stdout)

# Clean up dummy package
import shutil
shutil.rmtree(package_dir)

view raw JSON →