CLI tool
PyCQA/isort avatar
PyCQA/isort

isort needs Python 3.11, and its atomic mode stays off by default

A Python utility / library to sort imports.

6,966 stars766 forksPythonMIT

At a glance

What is it?
A sorter for Python imports that runs as a command, a library, an editor plugin and a pre-commit hook. It sorts alphabetically, groups by type into sections, and, with --atomic, refuses to rewrite a file in a way that breaks its syntax.
Who is it for?
Use isort when import order is decided by convention rather than by judgement, especially in a repository with a pre-commit hook already installed, since the hook path is the one that holds the ordering in place without asking anyone to remember a command. Think twice if you format with black, because the two disagree on a trailing comma by default and the compatibility guide is the place to settle that.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • PyCQA/isort6,966 ★ · +10
Star history
Repository2026-09-282026-11-15
PyCQA/isort7k7k

10 Stars in the last 48 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Grouping by type is the job, not alphabetizing

Alphabetical order is the easy half. The transformation shown in the project file puts `__future__` imports at the top, then standard library modules as bare imports, then third party names, then first party ones, with a blank line between each group. Within a group, names are sorted, and names imported from the same module get folded onto one line.

That folding is the part that generates arguments. The before and after example pulls two `from third_party` statements, fifteen names in all, into a single wrapped import, and merges three imports from `my_lib` into one line listing Object, Object2 and Object3. Anyone who wanted one symbol per line loses that.

So the tool's real decision is which category each import belongs to. A name it classifies as third party when you consider it first party ends up in the wrong section, and the fix is configuration rather than argument. The project ships a guide on custom sections and ordering for exactly this, since the sections are configurable rather than fixed.

--atomic is disabled by default because the wrong Python version breaks files

There is a mode that only writes a file if the result still parses:

bash
isort --atomic .

The explanation for why it is not on by default is more useful than the flag. Atomic mode blocks isort from running against code written using a different version of Python than the one isort itself is running under. Without that check, the tool can apply an output format that the target interpreter rejects, and you find out at import time rather than at review time.

That is a real hazard for a library that formats code for interpreters it is not running on. The default is off, and turning it on is a decision about which interpreter you trust, not a safety upgrade to flip blindly.

Python 3.11 and newer to run, Python 2 source to format

The version requirements pull in opposite directions. The package metadata declares requires-python of 3.11.0 or newer and the classifiers run from Python 3.11 through 3.15, on CPython and on PyPy. The stated support for Python 2 is about the code being formatted, not the interpreter running the formatter: isort can sort imports in Python 2 code while itself requiring a modern interpreter to run.

So a team maintaining a mixed repository can keep one isort install and point it at old modules. What it cannot do is run on the older interpreters.

The runtime surface is narrow in the other direction too. The only declared dependency is mypy-extensions at 1.1.0 or newer, and the project version is dynamic rather than hardcoded in pyproject.toml, which is the setuptools-scm pattern. The container build reflects the same shape: a python:3.13 base that installs uv, syncs with --all-extras and --frozen against uv.lock, then runs the test suite from scripts/test.sh.

include_trailing_comma defaults to False, which is where black disagrees

For the import styles that use parentheses, one option decides whether a comma follows the last name, and its default is False. Any project that formats with black will notice this immediately, because the prevailing convention in that ecosystem is to leave the trailing comma in place. The project links a dedicated compatibility guide for the two tools running together, which is where that disagreement gets resolved rather than argued about in review comments.

The related option is balanced_wrapping, which changes how the names inside a multi-line from import are distributed. With it enabled, isort picks the import length that produces the most balanced grid while staying below the maximum, rather than filling each line as far as it will go. It can be set in config or passed as -e on the command line.

The neighbouring knob is the indent setting, which accepts a count such as 4, the word Tab, or a quoted verbatim string. A quoted four space string is equivalent to 4. That flexibility is what lets a repository keep tabs or an unusual width without writing a plugin.

Twelve multi-line modes decide how a long from import wraps

Wrapping style is set by multi_line_output, which the documentation describes as having 12 possible settings. This is the setting that decides whether names hang indented under the opening parenthesis, whether the parenthesis stays with the from clause, and where the closing parenthesis lands. It is the setting that produces the largest diffs when a team changes it late, because every wrapped import in the repository reshapes at once.

It interacts with line_length rather than replacing it. The wrap point is where a from import passes the line length limit, so the two settings together decide whether a given import wraps at all and how it looks when it does. Anyone tuning one without the other tends to get confused about which change caused the reformat.

The project also supports adding and removing imports across files automatically, configured rather than typed per file, with a guide covering it.

isort:skip and isort:skip_file are the two escape hatches

Some imports must stay where they are, and the mechanism is a comment rather than a config exception list. On a single line, the text isort:skip at the end of the import tells the sorter to leave it alone. The same comment can also sit on the first line of a multi-line import.

For a whole file, isort:skip_file goes in the module docstring, and everything in that file is left untouched. The example in the project file shows an unsorted pair of imports surviving below a docstring that contains the marker.

The tradeoff is that both markers are comments in your source, so they travel with the code and cannot be expressed once in a central configuration. A file that must stay hand ordered keeps a permanent note in its docstring, and a reader who greps for isort:skip_file finds every one of them. The alternative, listing paths in config, keeps the decision out of the source but then travels badly when a file is moved or copied.

-c reports to stderr, which is the whole basis of the pre-commit hook

Verification mode is a separate way to use the tool. Run with -c, isort does not write anything and instead reports files whose imports are incorrectly sorted or formatted to stderr. Adding -v gives per-file lines, with a SUCCESS line naming a file that looks good and an ERROR line naming one whose imports are wrong.

bash
isort **/*.py -c -v

Because the report goes to stderr rather than stdout, it stays out of the way of pipelines that read standard output, and the non-zero exit status is what a hook acts on. The repository ships .pre-commit-hooks.yaml, and the project documents official pre-commit support, so the intended integration is a commit time check rather than a manual run before pushing.

Editor plugins are the other integration path, and they are community written rather than shipped here. The project keeps a list on its wiki and asks for pull requests that add documentation for editors not yet covered. Separately, the repository carries example isort plugin directories for formatting and for sorting, plus an example shared profile; these extend isort itself rather than an editor.

Editorial conclusion

Use isort when import order is decided by convention rather than by judgement, especially in a repository with a pre-commit hook already installed, since the hook path is the one that holds the ordering in place without asking anyone to remember a command. Think twice if you format with black, because the two disagree on a trailing comma by default and the compatibility guide is the place to settle that. Check the Python floor before you install, since isort requires Python 3.11 or newer even though it will happily reformat Python 2 source. Leave --atomic off unless your environment matches the interpreter your code targets, which is the reason the project disables it by default.

Frequently asked questions

What does isort do?

isort sorts Python imports alphabetically and separates them into sections by type, moving standard library, third party and first party imports into their own groups with blank lines between them. It runs as a command line utility, as a Python library through functions like isort.file and isort.code, and through editor plugins and a pre-commit hook.

How can I sort imports in Python with isort?

Install it with pip install isort, then run isort on specific files, on a directory with isort ., or on the whole tree with isort **/*.py. Use --diff to preview proposed changes without writing them, isort.file for one file from Python code, and isort.code to sort a string and get the result back.

How do you install isort?

The documented install is pip install isort. isort requires Python 3.11 or newer to run, declares mypy-extensions as its only dependency, and can still format Python 2 code since the version floor applies to the interpreter running the tool rather than the code it sorts.

What is isort and black, and how do they work together?

isort sorts and groups imports while black formats the rest of the file, and the two disagree by default on a trailing comma, since isort leaves include_trailing_comma False. The project publishes a compatibility guide for running them together, and the other common friction point is wrapping style, set by multi_line_output and line_length.

How do you use isort in vscode?

isort has no editor plugin of its own, so you install a community plugin. The project keeps a list of plugins on its wiki and invites pull requests adding documentation for editors not yet listed, and runs on Python 3.11 or newer.

Official sources

  1. License: MIT
  2. Project website
  3. PyCQA/isort on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pycqa-isort.svg)](https://hysenlabs.com/projects/pycqa-isort)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pycqa-isort.svg)](https://hysenlabs.com/projects/pycqa-isort)

Was this useful?