import-deps

library0.5.1pypypi✓ verified 23d ago

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.

testing

pip install import-deps

github ↗package ↗

INSTALL

IMPORT

SIG · IMPORT-DEPS

import-deps

testingpythonv0.5.1

Install

1.5s avg

Import

24ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.1 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.028s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.020s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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)

import_deps --version

Debug

Known issues

breakingDropped 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.

affects: 0.4.0+

breakingThe `--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`.

affects: 0.5.0+

gotchaWhen 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.

affects: 0.4.0+

gotchaVersion 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/`

affects: 0.5.0+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'import_deps'

The `import-deps` library or its executable script is not installed, or the Python interpreter cannot find it in its `sys.path`.

fix

Ensure the library is installed in your active Python environment by running `pip install import-deps`. If using a virtual environment, ensure it is activated.

ImportError: cannot import name '...' from partially initialized module '...' (most likely due to a circular import)

This error occurs in your project's code when two or more modules import each other in a way that creates a circular dependency, preventing Python from fully initializing one module before the other tries to access its contents. The `import-deps` tool itself can help you detect these issues in your codebase.

fix

Refactor your code to break the circular dependency. Common solutions include moving shared code to a new, independent module, using late imports (importing inside a function/method if the dependency is only needed there), or reframing the module structure. The `import-deps --check=circular` command can help identify the exact cycles.

AttributeError: module '...' has no attribute '...'

This error typically indicates that you are trying to access a name (function, class, variable) from a module that either does not define that name, or the name was not correctly imported or exposed. It can also occur in scenarios involving incorrect relative imports or partially loaded modules due to complex import structures.

fix

Verify that the name you are trying to access (e.g., `MyClass` in `module.MyClass`) is correctly defined and exported in the module. For packages, ensure that `__init__.py` files properly expose submodules or their contents if you expect them to be accessible via the parent package name. If it's a subpackage, ensure it's explicitly imported.

Usage: import_deps [OPTIONS] PATH...

This is not an error message but a common output when `import-deps` is run without or with incorrect arguments, indicating that the command-line interface (CLI) expects specific paths or options which were not provided or were malformed.

fix

Consult the `import-deps` documentation or run `import_deps --help` to understand the correct command-line arguments. For example, to analyze a single file, use `import_deps your_module.py`, or to check a package, use `import_deps your_package/`.

Upgrade

Version history

0.5.1latest on PyPI · released Jan 9, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/schettino72/import-deps ↗

packagehttps://pypi.org/project/import-deps/ ↗