py-import-cycles

0.6.2 verified Mon Apr 27 auth: no python

Detect import cycles in Python projects. Version 0.6.2 supports Python >=3.12, uses AST parsing (no runtime import). Available on PyPI.

pip install py-import-cycles

Common errors

error ImportError: cannot import name 'ImportCycleFinder' from 'py_import_cycles' ↓

cause Older version (pre-0.6) used a different API; or typo in symbol name.

fix

Use from py_import_cycles import find_cycles as primary API.

error ModuleNotFoundError: No module named 'py-import-cycles' ↓

cause Using hyphen in import statement instead of underscore.

fix

Import as import py_import_cycles (underscore).

error TypeError: find_cycles() got an unexpected keyword argument 'include_external' ↓

cause The signature changed in version 0.6; earlier versions may not support this.

fix

Update package: pip install --upgrade py-import-cycles. Check documentation for correct parameters.

Warnings

breaking Requires Python >=3.12; will not install or run on older versions. ↓

fix Use Python 3.12 or later.

gotcha Import path must be resolvable on sys.path; local modules need correct package structure or working directory. ↓

fix Run from project root or adjust Python path.

gotcha find_cycles uses AST parsing, so conditional imports or dynamic imports may not be detected. ↓

fix Static analysis only; consider runtime checks for dynamic imports.

Imports

ImportCycleFinder

wrong

from py-import-cycles import ImportCycleFinder

correct

from py_import_cycles import ImportCycleFinder

Hyphens are not allowed in Python identifiers; use underscores.

find_cycles
```
from py_import_cycles import find_cycles
```
The top-level find_cycles function is the quickstart entry point.

Quickstart

Scan a package for import cycles. The function returns a dictionary mapping module paths to lists of cycles.

from py_import_cycles import find_cycles

cycles = find_cycles('my_package', include_external=False)
if cycles:
    print('Cycles found:', cycles)
else:
    print('No cycles detected')