Skip to content

docs: clarify plugins folder sys.modules registration behavior#63634

Merged
potiuk merged 3 commits intoapache:mainfrom
shashbha14:docs/plugins-syspath-warning
Mar 16, 2026
Merged

docs: clarify plugins folder sys.modules registration behavior#63634
potiuk merged 3 commits intoapache:mainfrom
shashbha14:docs/plugins-syspath-warning

Conversation

@shashbha14
Copy link
Copy Markdown

The Modules Management documentation currently assumes that the dags, config, and plugins folders are equivalent and
all get added to the sys.path list. This is incorrect because the plugins folder also imports all .py files in this directory
and registers them in the sys.modules namespace under the filename without the directory structure. This means that if you
have a file named hdfs.py in the plugins/my_project directory, the file will end up as sys.modules["hdfs"], which can
cause name clashes with other packages, such as the PyPI hdfs package. For this-
Two warning sections have been added:

@shashbha14
Copy link
Copy Markdown
Author

The Static checks failure and the modification to output_pr_auto-triage.txt are unrelated to this documentation-only PR. They appeared after the merge commit from main. Could a maintainer please advise or re-run?

@potiuk potiuk merged commit 253be09 into apache:main Mar 16, 2026
71 checks passed
fat-catTW pushed a commit to fat-catTW/airflow that referenced this pull request Mar 22, 2026
…apache#63634)

Co-authored-by: Shashwati <shashwatibhattacaharya21.2@gmail.com>
Co-authored-by: Jarek Potiuk <jarek@potiuk.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Modules Management docs do not mention plugins folder's sys.modules registration behavior

2 participants