Why isort sorts 'test' above numpy but 'tests' below and how known_local_folder fixes it

Learn why isort 6.0.1 orders 'test' imports before numpy but 'tests' after, and how to fix it via known_local_folder in .isort.cfg or pyproject.toml config.

When using isort 6.0.1, two nearly identical test modules can end up with different import orders. One file that imports from a package named test places that import above numpy, while another file that imports from tests places it below. The difference is subtle, but it has a clear cause and an easy way to fix.

Reproducing the behavior

Consider two modules located under a/test/test_integration.py and b/tests/test_integration.py. After running isort, their imports end up ordered differently:

from test.asdasd import hello as greet_call
import numpy as npa
if npa.random.random() < 42:
    greet_call()

import numpy as npa
from tests.asdasd import hello as greet_call
if npa.random.random() < 42:
    greet_call()

The only difference is the module name in the from import: test versus tests. Yet isort sorts them into different sections, changing the relative order with numpy.

What causes the mismatch

The name test collides with the standard library module named test. isort’s default ordering prioritizes sections in this order:

('FUTURE', 'STDLIB', 'THIRDPARTY', 'FIRSTPARTY', 'LOCALFOLDER')

Because test appears in isort’s list of known standard library names, an import that starts with test is treated as a standard library import and sorted before third-party imports like numpy. The name tests is not recognized as standard library, so imports from tests are treated as local or first-party, which naturally puts them after numpy.

Fixing the ordering consistently

If test is actually part of your project and not the standard library, instruct isort to treat it as a local import. This makes the sorting behavior consistent with imports from tests. You can configure this using known_local_folder.

Using a .isort.cfg file:

[settings]
known_local_folder=test

Or via pyproject.toml:

[tool.isort]
known_local_folder = ["test"]

With this configuration, imports from test will no longer be placed in the standard library section, removing the discrepancy with tests.

Why this is worth knowing

Import order affects diffs, code reviews, and CI consistency. Seemingly harmless naming choices like calling a package test can silently change how isort classifies imports, leading to noisy reordering and confusion across modules. Understanding that isort classifies by section and that certain names are reserved as standard library prevents these surprises.

Practical takeaways

Either avoid naming your own packages after standard library modules, or explicitly tell isort how to classify them. If you already have a package named test and want stable ordering across files, set known_local_folder to test so isort treats it the same way it treats tests. This keeps third-party imports like numpy in a consistent position relative to your project’s modules and reduces unnecessary churn in your import blocks.