isort & Import Organization

Consistent import order makes diffs readable and prevents circular import surprises. Ruff's isort rules (I) handle this automatically - no separate isort install needed.

Recipe

[tool.ruff.lint.isort]
known-first-party = ["myapp"]
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]

uv run ruff check --fix .   # auto-sort imports

When to reach for this:

• Import blocks are inconsistently ordered across files
• Code review spends time on import nits
• Circular imports need clearer separation of stdlib vs local

Working Example

# Correct order (after ruff fix)
from __future__ import annotations
 
import os
from pathlib import Path
 
import httpx
from pydantic import BaseModel
 
from myapp.config import settings
from myapp.models import User

[tool.ruff.lint.isort]
known-first-party = ["myapp", "myapp_utils"]
force-single-line = false
lines-after-imports = 2

What this demonstrates:

• Future imports first, then stdlib, third-party, first-party, local
• Blank lines separate groups
• known-first-party tells ruff which packages are yours
• --fix reorders without manual editing

Deep Dive

Import Groups

Python Notes

# Prefer absolute imports in libraries
from myapp.services import billing
 
# Relative imports ok within a package
from .models import User

Gotchas

• Missing known-first-party - your packages sorted as third-party. Fix: list all first-party package names.
• isort + ruff both configured - conflicting rules. Fix: use ruff only; remove standalone isort.
• Star imports (from x import *) - lint flags and obscures origin. Fix: explicit imports except __init__.py re-exports.
• Circular imports from order - reordering doesn't fix design issues. Fix: restructure modules; use lazy imports or TYPE_CHECKING.
• Different order in __init__.py - re-exports confuse isort. Fix: per-file override or explicit __all__.

Alternatives

FAQs

Related

• Ruff Setup - ruff configuration
• Essential Lint Rules - I rules in context
• Black / Ruff Format - formatting (separate from imports)
• Linting & Formatting Best Practices - conventions

Stack versions: This page was written for Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.