isort: sorting Python imports from the command line and from Python

What isort actually fixes in a Python codebase

Import blocks rot quietly. Two developers add the same third-party package in different places, a lazy import lands above the standard library imports, and a from-import grows past the line length until someone wraps it by hand. isort targets exactly that surface: it sorts imports alphabetically, separates them into sections, and groups them by type. The README's own before-and-after example is the clearest statement of scope. Before, the sample file mixes os, sys, a __future__ import and two from-imports in an arbitrary order. After, __future__ comes first, then os and sys, then third_party, then my_lib, with the long third_party from-import wrapped in parentheses across two lines.

The audience is anyone who reviews Python diffs. That includes application teams that want a deterministic import block, library authors who care about __future__ placement, and maintainers of large repositories where a single contributor's editor settings would otherwise leak into every pull request. isort is not a linter in the sense of flagging unused names, and it does not reformat function bodies. It reads a file, rewrites the import region, and leaves the rest of the module alone. The project describes itself as a utility and library to sort imports, and the pyproject.toml classifier list marks it as Development Status 6, Mature.

How isort decides where an import goes

The mechanism is a parse, a classification and a re-emit. isort reads the source, identifies import statements, assigns each one to a section, orders the names inside each statement, and writes the block back. The section assignment is what makes the output look opinionated: standard library imports, third-party imports and first-party imports are separated by blank lines, and __future__ imports sit above everything else. The README's example shows the resulting shape directly, with third_party before my_lib.

Wrapping is a separate decision from ordering. The multi_line_output setting controls how a from-import wraps once it passes line_length, and the documentation points to 12 possible values for it. Balanced wrapping is a distinct mode: with balanced_wrapping set to True, or the -e flag on the command line, isort picks the wrap that produces the most even grid rather than filling the first line as far as it will go. The README shows the difference on a __future__ import, where balanced output splits the names two and two instead of three and one.

Indentation is configurable through the indent property, which accepts a number of spaces, the value Tab, or a verbatim quoted string. include_trailing_comma controls whether parenthesised import lists end with a comma, and it defaults to False. Two escape hatches exist for code isort should not touch: a trailing # isort:skip comment on a single import, and isort:skip_file inside the module docstring to exempt a whole file.

Installing isort and sorting your first file

isort is distributed on PyPI and requires Python 3.10 or newer to run, though the README notes it can still format Python 2 source. The README gives the install as a single command:

pip install isort

Once installed, the CLI is the fastest way to see what it does. Point it at specific files to sort them in place:

isort mypythonfile.py mypythonfile2.py

To see the proposed changes without writing them, pass --diff. This is the command to run first on an unfamiliar repository, because it prints the rewrite instead of applying it:

isort mypythonfile.py --diff

For a whole tree, run isort against the current directory. The README notes that with bash globstar enabled, isort . is equivalent to isort **/*.py:

isort .

There is also a Python API. The README gives two forms: isort.file("pythonfile.py") rewrites a file in place, and isort.code("import b\nimport a\n") returns the sorted source as a string without touching disk. The second form is the one to reach for in a script or a test, because it has no side effects:

import isort

sorted_code = isort.code("import b\nimport a\n")

For CI, the README documents a verification mode: running isort with -c (--check-only) leaves files untouched and writes any incorrectly sorted files to stderr. The same source also describes --atomic, which runs isort against a project and only applies changes if they do not introduce syntax errors. That flag is disabled by default, and the README gives the reason: it prevents isort from running against code written for a different Python version.

Where isort gets in your way

The configuration surface is the main cost. multi_line_output alone has 12 documented values, and the docs describe custom sections and ordering as options that change almost every aspect of how imports are organised. That flexibility is real, but it means two teams using isort on the same codebase can produce different output, and the diff noise from a settings change can be large. The README does not document a rollback path for a bad bulk rewrite, so the practical mitigation is to run --diff or commit the change in isolation before letting it touch a large tree.

The --atomic flag is a sharper trade-off than it first appears. It protects against a rewrite that breaks syntax, but the README states it is disabled by default precisely because it blocks isort from running against code written using a different version of Python. If you maintain a package that still ships Python 2 compatible source, atomic mode is the wrong tool.

isort is also the wrong tool when the problem is not ordering. It will not remove an unused import, resolve a circular dependency, or tell you that a name is shadowed. Adding or removing imports is described in the documentation as a separate configuration topic, not as part of the default sort. And on a project that already runs a formatter with its own import rules, running both without a shared profile is a recipe for a fight between two tools over the same lines. The README links a dedicated isort and black compatibility guide for exactly that situation.

isort versus ruff and the formatter you already run

Ruff is the alternative most Python teams weigh against isort, and the difference is scope. Ruff is a linter that also implements import sorting as one of its rules; isort does import sorting and nothing else. If you want one tool in CI that covers unused imports, style violations and import order, Ruff collapses those into a single binary. If you want the import block handled by a dedicated tool with its own plugin ecosystem, isort is that tool. The two are not mutually exclusive in principle, but running both on the same file means deciding which one owns the import block.

The other comparison is with the formatter you already run. isort is not a general formatter: it does not touch spacing inside functions, string quotes or trailing whitespace. The README explicitly points to a compatibility guide for black, which suggests the maintainers expect the two to be used together. The practical difference is that black decides line breaks across the whole file while isort decides them only inside import statements, so line_length and multi_line_output need to agree with the formatter's settings or the two will keep rewriting each other.

Maintenance, licence and what a 9.x upgrade costs

The repository is not archived, and the last push was on 2026-09-21. Releases 9.0.0 and 9.0.1 landed on 2026-08-26 and 2026-08-27, after a run of 9.0.0 betas in August 2026. The project is MIT licensed, and pyproject.toml declares license = "MIT" alongside the OSI Approved :: MIT License classifier. MIT is permissive: it allows commercial use and modification, and the only obligation it imposes is preserving the copyright notice and licence text. That is a description of the licence, not legal advice; check with your own counsel if the distinction matters to you.

The dependency footprint is small. pyproject.toml lists a single runtime dependency, mypy-extensions>=1.1.0, and requires-python is >=3.10.0. The classifiers cover CPython and PyPy from 3.10 through 3.15, so the supported interpreter range is wide. A Dockerfile in the repository builds on python:3.13, copies uv.lock, and runs the test suite through scripts/test.sh, which indicates the project tests against a pinned lockfile rather than floating dependencies.

Upgrade cost is mostly configuration drift. A major version bump is the moment to re-read the multi_line_output and custom sections documentation, because those are the settings most likely to change output. Versioning is driven by hatch-vcs from git tags, so the installed version tracks the tag it was built from.

Editorial conclusion

Adopt isort if you want import ordering enforced by a CLI, a Python API and editor plugins, and you are willing to write a config file that pins multi_line_output, line_length and profile. Do not adopt it expecting it to replace a linter or a full formatter: it only touches imports. Before rolling it out, run isort --diff on one real module to confirm the output matches your team's style, then decide between --check-only in CI and --atomic for local runs.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. PyCQA/isort on GitHub
4. README
5. Releases