importclean

A production-ready Python import cleaner. Detect and safely remove unused imports from an entire project while preserving code behavior, formatting, and style.

Features

• AST + LibCST analysis - detects every import variant without reformatting unrelated code
• Safe by default - never removes conditional, TYPE_CHECKING, try/except, or star imports
• Partial cleanup - removes only unused names from from x import a, b, c
• Alias detection - import numpy as np is kept when np is used
• Duplicate removal - collapses repeated identical import statements
• Circular import detection - finds cycles across the whole project
• Dependency graph - renders ASCII trees and Graphviz .dot files
• Heavy import suggestions - recommends lazy imports for expensive modules
• Import sorting - PEP 8 / isort-compatible grouping
• Post-clean validation - every modified file is re-parsed and compiled; originals are restored on failure
• Multiprocessing - scales to thousands of files
• Plugin system - add custom rules for project-specific policies
• .importclean.toml configuration

Installation

pip install importclean

For development:

git clone https://github.com/Madhav703/importclean
cd importclean
pip install -e ".[dev]"

Quick Start

CLI

importclean .

importclean . --dry-run

importclean . --check

# Show unified diffs
importclean . --diff

# Print import dependency graph
importclean . --graph

# Output results as JSON
importclean . --json

# Print statistics only
importclean . --stats

# Verify all files are syntactically valid
importclean . --verify

# Sort imports in PEP 8 order
importclean . --sort

# Write dependency graph as Graphviz .dot
importclean . --dot graph.dot

# Clean a single file
importclean myfile.py

# Verbose output (per-file details)
importclean . -v

Python API

from importclean import clean_project, clean_file

# Clean an entire project (dry run)
report = clean_project(
    path=".",
    dry_run=True,
    safe_mode=True,
)
print(report.summary())

# Clean a single file
file_report = clean_file("src/mymodule.py", dry_run=False)
print(f"Removed {len(file_report.unused)} unused imports")

Configuration

Create .importclean.toml in your project root:

ignore = [
    ".venv",
    "tests",
    "migrations",
]

safe_mode      = true
sort_imports   = true
remove_unused  = true
workers        = 4

Safety Guarantees

importclean will never:

• Remove an import that is actually used
• Remove star imports (from x import *)
• Remove __future__ imports
• Remove TYPE_CHECKING-guarded imports
• Remove try/except-wrapped imports
• Save a file that fails ast.parse() or compile() after transformation
• Alter any code outside of import statements

If post-clean validation fails, the original file is restored automatically and the error is reported.

What Gets Removed

Plugin System

import ast
from typing import Optional
from importclean import clean_project
from importclean.models import ImportInfo
from importclean.plugins.base import BaseRule, RuleResult
from importclean.plugins.registry import PluginRegistry

class NoPickleRule(BaseRule):
    name = "no-pickle"

    def check(self, node: ImportInfo, tree: ast.Module) -> Optional[RuleResult]:
        if node.module == "pickle":
            return RuleResult(
                import_info=node,
                message="Prefer json or msgpack over pickle.",
                should_remove=False,
            )
        return None

registry = PluginRegistry()
registry.register(NoPickleRule)

report = clean_project(".", dry_run=True, registry=registry)

Development

# Run tests
pytest

# Run tests with coverage
pytest --cov=importclean --cov-report=term-missing

# Lint
ruff check importclean tests

# Type check
mypy importclean

# Format
black importclean tests

License

MIT - see LICENSE.