py-import-cycles

What it is and what it does

py-import-cycles is a command-line tool that scans Python packages to find circular import dependencies. It uses Python's ast module to parse import statements and networkx to compute cycles, helping developers identify architectural problems where modules depend on each other in a loop. The tool walks the file tree of a given package, collects all Python modules, and reports any cycles it finds—useful for spotting structural weak points before they cause runtime issues or maintenance headaches.

The package is lightweight and straightforward: it doesn't integrate with Python's module finder or loader, so it analyzes only what's on disk. It's designed as a static analysis tool you run from the command line against your own codebase, making it a simple addition to code review or CI workflows when you want to check for import cycles without running the code.

Use it for:

• Check a new or refactored codebase for circular imports before merging to catch structural problems early.
• Audit legacy packages to identify and prioritize which import cycles to break during a refactoring effort.
• Integrate into CI/CD to fail builds when new circular imports are introduced.
• Analyze third-party packages you're considering adopting to assess their internal architecture quality.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Detects import cycles in Python projects by walking packages, collecting modules, extracting imports via ast, and computing cycles to identify structural weak points.

Yes, if you need to detect import cycles in Python projects. The tool is actively maintained, has no known vulnerabilities, and imposes minimal install friction. It's most useful for developers doing code reviews, refactoring, or enforcing architectural standards. Not necessary if your project already uses a linter or type checker that catches circular imports, or if import cycles aren't a concern in your workflow.

Install

py-import-cycles on PyPI

pip install py-import-cycles

uv add py-import-cycles

poetry add py-import-cycles

Installing py-import-cycles

Before you install

Low friction install with only two runtime dependencies (graphviz and networkx). Active maintenance with a recent commit on 2026-04-15 and no known vulnerabilities.

License in practice

MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart

pip install py-import-cycles
python3 -m py_import_cycles --packages /path/to/project/package

Requires Python 3.12 or later; graphviz and networkx must be available at runtime.

Verify before relying

• Whether graphviz system library (not just the Python package) is required as a separate install.
• Whether the tool produces actionable output formats (e.g., JSON, graph visualization) beyond console output.

Package facts

Evidence: py_import_cycles-0.6.2-py3-none-any.whl

Tags

More Quality Assurance packages