isort — Automatic Python Import Sorting Utility

Introduction

isort sorts Python imports alphabetically and automatically separates them into sections: standard library, third-party, and local imports. It removes the tedium of manually organizing import blocks and eliminates merge conflicts caused by differently ordered imports across team members.

What isort Does

• Sorts all import statements in Python files into standard library, third-party, and project sections
• Removes duplicate imports and merges from imports from the same module
• Supports multiple output styles including multi-line, vertical hanging indent, and force single line
• Runs as a CLI tool, Python API, pre-commit hook, or editor integration
• Checks files without modifying them using --check-only for CI enforcement

Architecture Overview

isort parses Python files to extract import statements, classifies each import by origin (stdlib, third-party, first-party, or local) using a combination of known module lists and heuristics, then re-emits the imports in sorted order. It preserves comments attached to imports and handles star imports, conditional imports, and TYPE_CHECKING blocks. Configuration cascades from command-line flags through pyproject.toml, setup.cfg, and .isort.cfg files.

Self-Hosting & Configuration

• Install via pip install isort or include in your dev dependencies with pip install isort[colors] for colored diff output
• Configure in pyproject.toml under [tool.isort] with options like profile = "black" for Black compatibility
• Use built-in profiles: black, google, pycharm, django, and others to match your team's style
• Add to pre-commit with the official pycqa/isort hook for automatic formatting on commit
• Set known_third_party and known_first_party lists to help isort classify ambiguous imports

Key Features

• Profiles for popular tools like Black, Google style, and Django to avoid configuration conflicts
• Git-aware mode that only processes files changed since a given revision
• Multi-line import styles with five distinct formatting options
• Float-to-top mode that moves imports to the top of the file above other code
• Plugin architecture for custom import classification and output formatting

Comparison with Similar Tools

• Black — formats all Python code but defers import ordering to isort; the two are designed to work together
• Ruff — includes isort-compatible import sorting as part of its fast Rust-based linter
• autopep8 — fixes PEP 8 violations broadly but has limited import sorting capabilities
• importmagic — auto-adds missing imports; isort focuses on sorting existing imports
• usort — Meta's import sorter with stricter defaults; isort offers more configuration flexibility

FAQ

Q: How do I make isort compatible with Black? A: Set profile = "black" in your isort configuration. This adjusts multi-line style and trailing comma behavior to match Black's output.

Q: Can isort handle conditional imports inside if blocks? A: Yes. isort detects and preserves imports inside if TYPE_CHECKING, try/except, and other conditional blocks without moving them to the top level.

Q: Does isort work with monorepos? A: Yes. Use src_paths configuration to tell isort which directories contain first-party code, and it will classify imports accordingly.

Q: How fast is isort on large codebases? A: isort processes files in parallel and is fast enough for most projects. For very large codebases, Ruff's built-in isort implementation is significantly faster.

Sources

• https://github.com/PyCQA/isort
• https://pycqa.github.io/isort/