Repository navigation
Folder with module name detected as source leads to false I001 error #10519
Description
Activity
- changed the title
[-]Folder with module name detected as source[/-][+]Folder with module name detected as source leads to false `I001` error[/+]on Mar 24, 2024 We could consider requiring an
__init__.pybut it would be a breaking change, I think.We could consider requiring an
__init__.pybut it would be a breaking change, I think.I see how a folder that is now correctly categorized as a source folder might not have an
__init__.pyin some cases, so this requirement could perhaps be something for the next major release indeed.If a source folder is required to contain any
*.pyfile, however, I cannot see how it would break current behaviour -- except for cases in which the sorting has now been incorrectly adapted to identified source folders.
So perhaps requiring any.pyfile could be an intermediate fix, whereas the next major release requires an__init__.py?If somebody could point me to the relevant source code, I could try and work on a PR.
Running the same Ruff check triggers a I001 error on the same file, categorizing wandb as Known(ThirdParty); the module categorization is cached, so I remove the .ruff_cache directory first to reproduce the error
Shouldn't the removal of the wandb directory be enough to invalidate the module categorization cache? The fact that you need to manually remove the cache to get the correct results also seems wrong.
Reacted by Dan RavivDiagnostics are cached on a per-file basis, where the "file" is the file in which the diagnostic is present. Changing other files on the filesystem doesn't invalidate the cache.
Changing the settings will also invalidate the cache. So if you add
wandbas aknown-third-partymodule (which is the suggested change), it will also reflect that change on re-run without clearing the cache mnanually.Say you were using a third party package in your requirements, but decided later to vendor it to make changes, turning it into a first party package. Then unless caches were manually cleaned you would get incorrect results from the isort check. Even worse, they could be inconsistent with CI checks, which can cause a lot of confusion. We ran into an issue like this today, and had to turn off caching as a result.
Say you were using a third party package in your requirements, but decided later to vendor it to make changes, turning it into a first party package. Then unless caches were manually cleaned you would get incorrect results from the isort check. Even worse, they could be inconsistent with CI checks, which can cause a lot of confusion. We ran into an issue like this today, and had to turn off caching as a result.
Honestly, I think this should be a separate issue about caching. It is only related in the sense that caching must somehow also handle the detection of third party folders. But if you propose improvements in the caching logic, I think it would make sense to do this separately from this issue (detection of source folders).
Reacted by Kevin LeWe're looking into changing how we cache data as part of our multifile analysis work. It will allow us to invalidate caches based on dependencies.
Reacted by Kevin LeI would echo the same concern, it is really difficult for the end-users to pick up the error.
I had the same issue when using
wandb. I ensured my local and remote CI tests have consistent environments but the differences still persist until I realised that a local folder namewandbis created.Better error message is needed if we can't have a quick fix easily.
Reacted by Udit Ranasaria- marked Ruff unexpectedly moving third party packages to first party section #16376 as a duplicate of this issue
on Feb 26, 2025 We should prioritize resolving this issue. There is a known workaround, but it comes up regularly, and reproducing it is a ton of work for users (and us).
Reacted by Tyler BoddySpargo, Evgeniy Dobroselskiy, Jonathan B. Coe and Anssi@dylwil3 do you have any ideas on how we could improve the
wandbcase described here? What I understand is that your most recent change won't help with this because it will still considerwandbas a possible namespace package (which is correct because Python would do the same)Reacted by DylanA slightly naive workaround would be to provide a default list of known third parties, including
wandbfor this specific issue. I see two downsides of such a list:- Adding maintenance effort
- Not necessarily expected behaviour for new users
However, I don't see a generalizable solution, so perhaps such a specific list would be a starting point until it grows to an unmaintainable scale.
8 remaining items
I wonder if skipping folders that are ignored by git (optionally) might be a nice generic fix for avoiding temporary files?
- marked I001 import sorting rule behaves differently in CI vs local with identical files and config #20483 as a duplicate of this issue
on Sep 19, 2025 - added a commit that references this issue
on Nov 14, 2025 IMO it can easily happen with some other python packages, and it will be equally confusing to debug. I suggest adding an option to somehow adjust how a package is treated local or not. And maybe somehow make isort variant which will not be dependent on local-ness of the module (and existence of any name-matching dirs) at all.
If you want to "not depend on local-ness", you can just remove the first-party and local sections -- this already exists:
[lint.isort] section-order = [ "future", "standard-library", "third-party", ]
Then all first-party and third-party imports will be grouped together.
You can use no-sections if you don't want isort to distinguish between first and third party packages
This should help, thanks! Would be nice to maybe make a better default specifically for local dirs: e.g. when package exists both as third-party and as a local dir - do not propose import order fixes, and do not propose moving it out of the third-party section.
It should be relatively less common these days to intentionally actually have a local dir package to shadow a global package (given that these days it's so simple to have venvs, so it's easy to not put unneded global packages into the env in the first place). So maybe if a package exists as both third-party and local - actually consider it third-party.
And also, somehow python itself doesn't get confused and still loads the global wandb, and not breaks saying that the local folder
wandbdoesn't contain anything loadable. But maybe it requires more sophisticated resolution logic.when package exists both as third-party and as a local dir - do not propose import order fixes, and do not propose moving it out of the third-party section.
Ruff does not really have a way of knowing what third-party means beyond "not first party", essentially. That is: Ruff does not know what packages you have declared in your
pyproject.toml, nor does it look for a virtual environment or anything like that.One of the big ironies of import sorting is that it feels like it should belong to the formatter, but when you look at the information it would need to understand in order to match user's expectations for first/third-party, it really needs to belong to something closer to a type checker or a package manager.
If only some organization built a formatter, package manager, and a type checker 😄
See #21520 for a possible way forward on this.
Maybe making a heuristic, that a directory without
__init__.pyor without any python files considered not-first-party? How does Python itself decide that it should skip the local wandb dir?I think the main problem here is coming up with a default setting which does not depend on existence of local folders and on CI / no-CI env... And it's really a painful thing to debug :(
Maybe making a heuristic, that a directory without init.py or without any python files considered not-first-party? How does Python itself decide that it should skip the local wandb dir?
A directory without an
__init__.pycan still be a namespace package. Checking recursively for Python files would be more likely to be a correct heuristic but could be more expensive to do.What Python actually does will necessarily involve finding the virtual environment: As described in the PEP, Python will look first at your local directory structure and see the directory
foowith no Python files in it, say. It will record that it found this as a "potential" namespace package. But then it will search your virtual environment. If it finds an honest Python packagefoothere, then that is the resolved module. If it doesn't, then it will resolve to the local directoryfooas an implicit namespace package.So we couldn't mimic that exact behavior unless we found your virtual environment. But having declared dependencies as in the
uv metadataidea should give the same behavior (unless someone has an environment that doesn't match the declared one).Reacted by David Vo- marked ruff misclassifies 'build' package as first-party due to gitignored
build/artifact directory #24321 as a duplicate of this issueon Mar 31, 2026 Bump, also just ran into this with
wandb, was stumped for quite a bit
This issue affects the expected sorting of imports in Python and hence (incorrectly) triggers a
I001error.When there is a folder that has the same name as a module, it is (possibly incorrectly) identified as
SourceMatch. Ruff then categorizes the module asKnown(FirstParty)and adapts the expected sorting accordingly.This happens commonly, but not exclusively, when using the wandb library because it creates a
wandbfolder, as discovered in ChartBoost/ruff-action#20.To reproduce the issue, create a Python file with these imports (I called it
test.py):In the initial scenario, there is a
wandbdirectory:Running Ruff to check the import sorting:
The checks pass,
wandbhas been categorized asKnown(FirstParty)Now remove the
wandbdirectory:Running the same Ruff check triggers a
I001error on the same file, categorizingwandbasKnown(ThirdParty); the module categorization is cached, so I remove the.ruff_cachedirectory first to reproduce the error:This is now the expected sorting that is generated when calling
ruff --fixcall above:This configuration option fixes the issue properly (see ChartBoost/ruff-action#20 (comment)):
However, it is difficult for users to identify the issue and fix the configuration accordingly. I think a better solution would be to have a more robust source directory detection.
A heuristics like checking for
__init__.pyor generally the presence of*.pyfiles as a condition might be a solid starting point for Python.