py-import-cleaner

A production-ready CLI tool that automatically detects and removes unused imports across Python projects safely.

Features

• AST-based detection — Accurate unused import detection using Python's Abstract Syntax Tree
• Safe removal — Removes unused imports while preserving formatting
• Safety rules — Never removes imports inside try/except ImportError or referenced in __all__
• Dry-run mode — Preview what would be removed without making changes
• Diff preview — See exact changes before applying
• Recursive scanning — Scan entire projects with smart directory exclusion
• Configurable — Via .importcleaner.toml, pyproject.toml, or CLI options
• Pre-commit integration — Use as a pre-commit hook
• CI-friendly — Non-zero exit code when unused imports are found

Installation

pip install py-import-cleaner

Or install from source:

git clone https://github.com/aneeshrao/py-import-cleaner.git
cd py-import-cleaner
pip install -e ".[dev]"

Quick Start

Scan for unused imports

py-import-cleaner .

Remove unused imports

py-import-cleaner . --fix

Preview changes (dry run)

py-import-cleaner . --dry-run

Show diff of proposed changes

py-import-cleaner . --diff

CLI Options

Option	Description
--fix	Remove unused imports
--dry-run	Show results without changes
--diff	Show file diff of proposed changes
--verbose	Detailed logging
--exclude	Exclude directories (repeatable)
--include	Only scan selected paths (repeatable)
--config	Path to config file

Configuration

Create a .importcleaner.toml file in your project root:

[tool.importcleaner]
exclude = ["tests", "migrations"]
ignore_modules = ["typing"]

Or add to your existing pyproject.toml:

[tool.importcleaner]
exclude = ["tests", "migrations"]
ignore_modules = ["typing"]

Pre-commit Integration

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/aneeshrao/py-import-cleaner
    rev: v1.0.0
    hooks:
      - id: py-import-cleaner

Example Output

3 unused imports found

accounts/views.py
  line 3: import sys

utils/helpers.py
  line 5: from datetime import datetime

Run with --fix to remove them

Safety Rules

The tool will never remove imports that are:

• Inside try/except ImportError blocks (optional dependency patterns)
• Referenced in __all__ (public API exports)

# This import will NOT be removed
try:
    import uvloop
except ImportError:
    pass

Library Usage

from py_import_cleaner import analyze_source, fix_source

source = """
import os
import sys

print(os.getcwd())
"""

result = analyze_source(source)
for unused in result.unused_imports:
    print(f"Unused: {unused}")

fixed = fix_source(source, result)
print(fixed)

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check src/ tests/

# Run type checker
mypy src/

Supported Import Types

• import module
• import module as alias
• from module import name
• from module import name as alias
• from module import name1, name2, name3

Default Excluded Directories

• .git
• .venv / venv
• __pycache__
• node_modules
• .mypy_cache
• .pytest_cache
• .ruff_cache
• .tox
• dist / build

Requirements

• Python >= 3.9

License

MIT