reportImportCycles.md

April 8, 2026 · View on GitHub

Overview

reportImportCycles is a diagnostic that flags cycles in your Python import graph, which can lead to confusing bugs and maintenance issues. Cyclic imports can cause modules to be partially initialized, resulting in runtime errors or unexpected behavior.

Representative Issues

  • #3003: Ensure Pylint plugins are installed and configured for correct diagnostics.
  • #3102: Default argument types in functions should match annotated parameter types.
  • #3853: Configure packageIndexDepths and ensure the correct Python environment for auto-imports.
  • #3855: Enable Python indexing in VSCode for auto-imports.
  • #4012: Override diagnostic severity for import cycles globally in pyright.
  • #4163: Ensure consistency in type stubs between Pyright CLI and Pylance settings.
  • #495: Use the exclude property in config files to prevent analysis of unwanted folders.
  • #5200: Customize diagnostic rule severities by type checking mode.
  • #531: Use # pyright: reportImportCycles=none to suppress cyclical import warnings for a file/module.
  • #5887: Ensure abstract base classes implement all abstract methods.
  • #6300: Exclude unnecessary folders like .venv for performance.
  • #715: Prefer typing.Dict over dict[t, t] for compatibility.

Examples

# module_a.py
from module_b import helper  # Warning: Import cycle detected

def func_a():
    return helper()

# module_b.py
from module_a import func_a  # Circular dependency!

def helper():
    return func_a()

Fix — move shared code into a third module or use lazy imports:

# module_a.py
from module_shared import helper

# module_b.py
from module_shared import func_a

Fix — use TYPE_CHECKING for type-only imports:

from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from module_b import MyClass  # Only used for type hints

Common Fixes & Workarounds

  1. Refactor code to break import cycles, possibly by moving imports inside functions or reorganizing modules.
  2. Use the exclude property in your pyrightconfig.json to avoid analyzing unnecessary folders.
  3. Suppress specific import cycle warnings with # pyright: reportImportCycles=none in affected files.
  4. Ensure your Python environment and type stubs are consistent and properly configured.
  5. See the Pyright configuration documentation for details on configuring this rule.

See Also