py-import-checker

A zero-dependency Python tool that scans a project and reports broken imports.

It loads Python files using the standard library and reports import failures before they reach runtime.

Features

• Zero dependencies (Python standard library only)
• Supports src/ layouts with --src
• Reports ImportError and ModuleNotFoundError
• Ignores runtime errors raised during module execution
• Skips virtual environments and build directories
• Works in CI with meaningful exit codes
• Auto-fix broken imports with --fix (installs missing packages via pip)
• Dry-run preview with --dry-run (shows what would be installed, no side-effects)

Installation

pip install py-import-checker

Usage

py-import-checker
py-import-checker path/to/project
py-import-checker . --src src/
py-import-checker . --src src/ --src lib/
py-import-checker . --glob "app/**/*.py"
py-import-checker . --verbose

Auto-fix

Install every missing package detected during the scan:

py-import-checker . --fix

Preview what would be installed without touching the environment:

py-import-checker . --dry-run

After a successful --fix, the tool re-scans automatically to confirm all imports are resolved.

Python API

from pathlib import Path

from py_import_checker.checker import check_directory

result = check_directory(
    Path("src"),
    extra_paths=[Path("src")],
)

if not result.success:
    for error in result.errors:
        print(error.file, error.message)

Pre-commit

repos:
  - repo: https://github.com/matthieugraziani/py-import-checker
    rev: v0.2.5
    hooks:
      - id: py-import-checker
        args: [--src, src/]

Development

pip install hatch
hatch env create
hatch run test
hatch run lint
hatch run type-check

License

MIT