---
id: py-import-cycles
version: "0.6.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# py-import-cycles — Detect import cycles in Python projects

License: permissive · Maintenance: active · Downloads: 149.9K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 149.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

detect import cycles python, circular import detection, python module dependency cycles, import cycle analyzer, structural code analysis python, dependency graph cycles, python package quality check, static-analysis, code-quality, architecture

[View on SkillFed](https://skillfed.io/packages/py-import-cycles) · [View on PyPI](https://pypi.org/project/py-import-cycles/)