# isort — Automatic Python Import Sorting Utility

> isort is a Python utility that automatically sorts and organizes import statements according to PEP 8 and configurable profiles. It integrates with pre-commit hooks, editors, and CI pipelines to keep imports consistent across projects.

## Install

Save in your project root:

# isort — Automatic Python Import Sorting Utility

## Quick Use
```bash
pip install isort
isort .
# or check without modifying
isort --check-only --diff .
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-0e072ba0
Author: AI Open Source