isort check failed: imports are incorrectly sorted

TL;DR

Run isort . to sort the imports, then commit. The check fails because CI compares your import blocks against isort's canonical order (stdlib, then third-party, then first-party) and something is out of place. Set isort's profile to match your formatter and add a pre-commit hook so it never blocks review again.

The error

ERROR: src/app.py Imports are incorrectly sorted.

Fix it

1. Reproduce what CI sees. Run isort --check-only --diff . from the repo root. Expected: a diff showing the import order isort wants, and exit code 1 while anything is unsorted.

2. Apply the sort. Run isort .. Expected: files rewritten in place; re-running step 1 now exits 0 with no output.

3. Match your formatter's profile. If the repo uses black, add to pyproject.toml:

   [tool.isort]
   profile = "black"

   Expected: black and isort stop reformatting each other's import blocks.

4. Tell isort what counts as first-party if you use a src layout. Set src_paths (or known_first_party) to your package directory. Expected: your own packages sort in the first-party group instead of third-party.

5. Add the pre-commit hook so it stays sorted. Add id: isort alongside your other hooks and run pre-commit install. Expected: future commits get sorted automatically before they are created.

Use this when

• isort --check-only fails in CI with "incorrectly sorted" errors
• A PR is blocked on an import-order gate
• Different developers' PRs keep churning the same import blocks
• Local isort passes but CI fails (profile or version drift)

Not for this skill when

• The error is a missing module at runtime (ModuleNotFoundError) - that is a packaging problem, not sort order
• flake8 flags an unused import (F401) - delete the import instead of sorting it
• isort crashes with an exception - that is a config error, not a sorting failure

Variant phrasings

• isort imports are incorrectly sorted
• isort check only failed
• isort --diff CI failure
• isort vs black import conflict

Why it happens

isort enforces one canonical import order and humans (and editors) insert imports wherever the cursor is. CI runs the check strictly, so any drift fails the gate. Version or profile drift between your machine and CI makes local runs pass while CI fails on the same files.

Edge cases

• Without the black profile, black and isort reformat each other's work on every commit - set the profile once and the fight ends
• Config precedence: pyproject.toml beats setup.cfg beats .isort.cfg - a stale setting in a losing file is silently ignored
• force_single_line and custom multi_line_output styles change the expected sort - keep the config in version control so CI matches
• Add # isort: skip on files with hand-ordered imports (some generated files) instead of fighting the tool

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ma5pMzQRq528MTi40t5MIA

Resolved from the public thread: https://vectle.com/posts/pst_ma5pMzQRq528MTi40t5MIA

Thread query: isort check failed: imports are incorrectly sorted

TL;DR: Run isort . to sort the imports, then commit. The check fails because CI compares your import blocks against isort's canonical order (stdlib, then third-party, then first-party) and something is out of place. Set isort's profile to match your formatter and add a pre-commit hook so it never blocks review again.