{"id":2971,"library":"import-deps","title":"import-deps","description":"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.","status":"active","version":"0.5.1","language":"python","source_language":"en","source_url":"https://github.com/schettino72/import-deps","tags":["dependency-analysis","cli-tool","static-analysis","module-imports"],"install":[{"cmd":"pip install import-deps","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"Used for higher-level package dependency analysis.","symbol":"ModuleSet","correct":"from import_deps import ModuleSet"},{"note":"Used for low-level AST-based import extraction from a single file path.","symbol":"ast_imports","correct":"from import_deps.analyzer import ast_imports"}],"quickstart":{"code":"import os\nimport pathlib\nimport subprocess\n\n# Create a dummy package for demonstration\npackage_dir = \"my_dummy_package\"\nos.makedirs(f\"{package_dir}/sub_module\", exist_ok=True)\n\nwith open(f\"{package_dir}/__init__.py\", \"w\") as f:\n    f.write(\"from .module_a import func_a\\n\")\n\nwith open(f\"{package_dir}/module_a.py\", \"w\") as f:\n    f.write(\"import os\\nfrom .sub_module.module_b import func_b\\ndef func_a(): pass\\n\")\n\nwith open(f\"{package_dir}/sub_module/module_b.py\", \"w\") as f:\n    f.write(\"import sys\\ndef func_b(): pass\\n\")\n\n# Run import-deps CLI to analyze the package and output JSON\nprint(f\"\\nAnalyzing '{package_dir}' with import-deps CLI:\\n\")\ncmd = [\"import_deps\", package_dir, \"--json\"]\nresult = subprocess.run(cmd, capture_output=True, text=True, check=True)\nprint(result.stdout)\n\n# Clean up dummy package\nimport shutil\nshutil.rmtree(package_dir)\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.10+ or pin `import-deps<0.4.0` in your project dependencies.","message":"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`.","severity":"breaking","affected_versions":"0.4.0+"},{"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`.","message":"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.","severity":"breaking","affected_versions":"0.5.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.4.0+"},{"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/`","message":"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.","severity":"gotcha","affected_versions":"0.5.0+"}],"env_vars":null,"search_vec":"'0.5.1':62 '2026':66 'activ':58 'analysi':74,80 'analyz':18,50 'ast':46 'built':41 'cadenc':71 'circular':31 'cli':12,76 'cli-tool':75 'dep':3,6 'depend':20,32,73 'dependency-analysi':72 'design':14 'ensur':48 'execut':54 'find':16 'help':27 'identifi':28 'import':2,5,19,35,38,83 'import-dep':1,4 'indic':67 'inner':37 'issu':29 'januari':65 'librari':10,56 'like':30 'maintain':59 'modul':23,47,51,82 'module-import':81 'packag':25 'python':9,22,43 're':34 're-import':33 'regular':69 'releas':63,70 'standard':45 'static':79 'static-analysi':78 'tool':13,77 'upon':42 'version':61 'within':21","created_at":"2026-04-11T09:15:27.435814+00:00","updated_at":"2026-04-16T15:43:10.140480+00:00","problems":[{"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.","cause":"The `import-deps` library or its executable script is not installed, or the Python interpreter cannot find it in its `sys.path`.","error":"ModuleNotFoundError: No module named 'import_deps'"},{"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.","cause":"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.","error":"ImportError: cannot import name '...' from partially initialized module '...' (most likely due to a circular import)"},{"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.","cause":"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.","error":"AttributeError: module '...' has no attribute '...'"},{"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/`.","cause":"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.","error":"Usage: import_deps [OPTIONS] PATH..."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5.1","cli_name":"import_deps","cli_version":"0.5.1","type":"library","homepage":null,"github":"https://github.com/schettino72/import-deps","docs":null,"changelog":null,"pypi":"https://pypi.org/project/import-deps/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}