isort

8.0.1 verified Tue May 12 auth: no python install: verified quickstart: verified

isort is a Python utility and library designed to sort imports alphabetically, automatically separating them into sections by type. It provides a command-line utility, a Python library, and plugins for various editors to streamline import organization. Currently at version 8.0.1, isort maintains an active development pace with frequent major and minor releases, ensuring ongoing feature enhancements and bug fixes.

pip install isort

Common errors

error Imports are incorrectly sorted. ↓

cause The import statements in the file do not adhere to isort's configured sorting and formatting rules.

fix

Run isort . (or isort <path/to/file.py>) from your terminal to automatically sort and fix the imports. If using pre-commit, ensure isort is configured correctly.

error isort conflicts with black ↓

cause isort's default sorting behavior is incompatible with black's formatting style, causing them to continuously undo each other's changes, especially when used together in pre-commit hooks.

fix

Configure isort to use the 'black' profile. Add profile = black under the [tool.isort] section in your pyproject.toml or in a .isort.cfg file. Alternatively, run isort . --profile black.

error ModuleNotFoundError: No module named 'isort' ↓

cause The 'isort' package is not installed in the Python environment currently being used by your terminal, editor, or automation tool (like a pre-commit hook).

fix

Install isort using pip: pip install isort. Ensure you install it in the correct Python environment (e.g., your project's virtual environment).

error Found <module> import while parsing, but <section> was not included in the `sections` setting of your config. ↓

cause isort encountered an import statement for a module that it couldn't categorize into one of the defined sections (e.g., STDLIB, THIRDPARTY, FIRSTPARTY, LOCALFOLDER) in your configuration.

fix

Define the missing section in your isort configuration (e.g., in pyproject.toml or .isort.cfg) by adding it to the sections setting, and/or explicitly tell isort which modules belong to which section using known_first_party, known_third_party, known_local_folder, etc.

error isort was told to use the settings_path: <path> as the base directory or file that represents the starting point of config file discovery, but it does not exist. ↓

cause isort cannot find the configuration file or directory specified by the `settings_path` argument or implied by its discovery mechanism.

fix

Ensure the path provided for settings_path (or the location where you expect isort to find its config) is correct and the file/directory actually exists. Use isort --show-config to debug how isort is discovering its configuration.

Warnings

breaking Major versions of `isort` regularly drop support for older Python versions. Version 7.0.0 dropped support for Python 3.9, and version 6.0.0 dropped Python 3.8. Current versions (8.x) require Python >= 3.10.0. ↓

fix Ensure your project's Python interpreter meets the minimum requirement for your `isort` version or pin `isort` to an older version compatible with your environment.

breaking isort v8.0.0 removed the `setuptools` plugin and deprecated old finders flags and legacy finder logic. Version 6.1.0 also dropped the use of the non-standard `pkg_resources` API. Integrations relying on these components will break. ↓

fix Review your `isort` configuration and any custom scripts for usage of `setuptools` plugin or legacy finder flags. Update integrations to use `isort`'s official programmatic API or standard configuration methods. Refactor any code depending on `pkg_resources` for dependency discovery.

gotcha `isort` can conflict with other code formatters, notably `Black`, if not configured correctly. Both tools format imports but with different default styles. ↓

fix Always configure `isort` with the `black` profile when using it alongside `Black`. This can be done via `isort --profile black` on the command line, or by adding `profile = "black"` under `[tool.isort]` in your `pyproject.toml` or `[isort]` in `.isort.cfg`.

gotcha `isort` supports multiple configuration file formats (`pyproject.toml`, `.isort.cfg`, `setup.cfg`, `tox.ini`, `.editorconfig`), which can lead to confusion regarding precedence and correct syntax. For `pyproject.toml`, settings must be under `[tool.isort]`. ↓

fix Consolidate your configuration into a single, preferred file format like `pyproject.toml` (using `[tool.isort]`) or `.isort.cfg` (using `[settings]` or `[isort]`). Use `isort --verbose` to confirm which configuration file is being used for a given path.

gotcha The `--atomic` flag, which prevents `isort` from applying changes that introduce syntax errors, is disabled by default. Using it can prevent `isort` from running against code written using a different Python version than the one `isort` is run with. ↓

fix Be mindful when using `--atomic` in CI/CD environments, especially in projects with diverse Python version targets. It's often safer to rely on your test suite or linter to catch syntax errors after `isort` runs without `--atomic`.

gotcha Prior to version 8.0.0, `isort` had an edge case where it could incorrectly handle `__future__` imports. While fixed in 8.0.0, older versions might exhibit subtle issues. ↓

fix Upgrade to `isort` 8.0.0 or newer if your project relies heavily on `__future__` imports and you encounter unexpected formatting behavior. Otherwise, carefully review `isort`'s output on such files.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.20s 18.5M

3.10 alpine (musl) - - 0.21s 18.5M

3.10 slim (glibc) wheel 1.5s 0.13s 19M

3.10 slim (glibc) - - 0.13s 19M

3.11 alpine (musl) wheel - 0.28s 20.5M

3.11 alpine (musl) - - 0.32s 20.5M

3.11 slim (glibc) wheel 1.7s 0.26s 21M

3.11 slim (glibc) - - 0.24s 21M

3.12 alpine (musl) wheel - 0.25s 12.3M

3.12 alpine (musl) - - 0.27s 12.3M

3.12 slim (glibc) wheel 1.5s 0.29s 13M

3.12 slim (glibc) - - 0.26s 13M

3.13 alpine (musl) wheel - 0.23s 12.1M

3.13 alpine (musl) - - 0.25s 12.0M

3.13 slim (glibc) wheel 1.6s 0.23s 13M

3.13 slim (glibc) - - 0.23s 12M

3.9 alpine (musl) wheel - 0.17s 18.4M

3.9 alpine (musl) - - 0.19s 18.4M

3.9 slim (glibc) wheel 2.1s 0.16s 19M

3.9 slim (glibc) - - 0.14s 19M

Imports

isort
```
import isort
```
The `isort` module is imported directly for programmatic access to functions like `isort.code()` or `isort.file()`.

Quickstart verified last tested: 2026-04-24

Demonstrates programmatic use of `isort` to sort a string of Python code and check if it's correctly sorted. The `isort.code()` function takes a string of code and returns the sorted version, while `isort.check_code()` verifies compliance.

import isort

unsorted_code = '''import os
import sys
from third_party import lib
from . import local_module'''

sorted_code = isort.code(unsorted_code)
print(sorted_code)

# Example of checking if code is sorted correctly
is_sorted = isort.check_code(sorted_code)
print(f"Is the code sorted correctly? {is_sorted}")