isort

Project Overview

isort is a Python utility for organizing import statements: it sorts them alphabetically and automatically separates them into sections by type such as standard library, third-party, and local imports. It offers a command line tool, a Python library API, and plugins for many editors, keeping imports tidy across your project. isort requires Python 3.11+ to run and can also format Python 2 code.

Delegate import sorting to the tool and never think about it again.

Key Features

• Automatic sorting: orders import statements alphabetically
• Section grouping: separates imports into sections by source type automatically
• Diff preview: --diff shows proposed changes before applying them
• Atomic mode: --atomic applies changes only when they introduce no syntax errors
• Library API: callable from Python code through the isort interface
• Check mode: --check-only validates import order in CI without modifying files
• Fine-grained config: multi-line output modes, indentation, custom sections, and more
• Selective skipping: skip specific imports or files with isort:skip comments

Target Audience

• Python developers
• Open-source maintainers
• Code standards enforcers
• CI pipeline maintainers
• Teams using Black

Quick Start

1. Install isort

pip install isort

2. Sort specific files

isort mypythonfile.py mypythonfile2.py

3. Process a whole project recursively

isort .

4. Validate without modifying in CI

isort . --check-only

Core Advantages

• Works out of the box: defaults satisfy most projects
• Black compatible: an official guide covers Black-compatible configuration
• pre-commit support: officially supported pre-commit hook integration
• Deeply configurable: nearly every sorting detail can be customized

System Requirements

Notes

• Version requirement: running isort requires Python 3.11 or later
• Multi-line modes: multi_line_output offers 12 wrapping styles; pick one per team convention
• Atomic off by default: --atomic is disabled by default to avoid cross-version misjudgment