This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 253be09a001 docs: clarify plugin folder module registration in
modules_management (#63634)
253be09a001 is described below
commit 253be09a00114aec5ffda2602256e8c03f52e55e
Author: Shashwati Bhattacharyaa <[email protected]>
AuthorDate: Mon Mar 16 16:54:40 2026 +0530
docs: clarify plugin folder module registration in modules_management
(#63634)
Co-authored-by: Shashwati <[email protected]>
Co-authored-by: Jarek Potiuk <[email protected]>
---
.../modules_management.rst | 26 ++++++++++++++++++++++
1 file changed, 26 insertions(+)
diff --git
a/airflow-core/docs/administration-and-deployment/modules_management.rst
b/airflow-core/docs/administration-and-deployment/modules_management.rst
index 9ba4361e0ff..798499b5d0b 100644
--- a/airflow-core/docs/administration-and-deployment/modules_management.rst
+++ b/airflow-core/docs/administration-and-deployment/modules_management.rst
@@ -141,6 +141,19 @@ Airflow, when running dynamically adds three directories
to the ``sys.path``:
- The ``config`` folder: It is configured by setting ``AIRFLOW_HOME`` variable
(``{AIRFLOW_HOME}/config``) by default.
- The ``plugins`` Folder: It is configured with option ``plugins_folder`` in
section ``[core]``.
+.. warning::
+
+ Unlike the ``dags`` and ``config`` folders, which are simply appended to
``sys.path``
+ (making them available for explicit imports only), the ``plugins`` folder's
``.py`` files
+ are **actively imported at Airflow startup** and registered in
``sys.modules`` under the
+ bare filename as a top-level module. The subdirectory structure is ignored
when
+ determining the module name, so a file at
``plugins/my_project/operators/hdfs.py`` is
+ registered as ``sys.modules["hdfs"]``, not
``sys.modules["my_project.operators.hdfs"]``.
+ Because ``sys.modules`` is populated at process startup, any ``import
hdfs`` anywhere in
+ the process — including inside installed providers or third-party libraries
— will resolve
+ to the plugin file instead of the intended package. See
:ref:`plugins:loading` for the
+ full plugin loading lifecycle.
+
.. note::
The Dags folder in Airflow 2 and 3 should not be shared with the webserver.
While you can do it, unlike in Airflow 1.10,
Airflow has no expectations that the Dags folder is present in the
webserver. In fact it's a bit of
@@ -186,6 +199,19 @@ folders that will clash with other packages already
present in the system. For e
create ``airflow/operators`` subfolder it will not be accessible because
Airflow already has a package
named ``airflow.operators`` and it will look there when importing ``from
airflow.operators``.
+.. warning::
+
+ For the ``plugins`` folder, the name-collision risk extends to ``.py``
files at **any
+ depth**, not just the top level. Because plugin files are automatically
imported at
+ startup and registered in ``sys.modules`` by bare filename alone, a file at
+ ``plugins/my_company/operators/hdfs.py`` registers as
``sys.modules["hdfs"]``, silently
+ shadowing the PyPI ``hdfs`` package. This can break providers that depend
on it — for
+ example, ``apache-airflow-providers-apache-hdfs`` imports ``from hdfs
import HdfsError``,
+ which fails with ``ImportError`` if a plugin file named ``hdfs.py`` exists
anywhere in
+ the plugins folder. Note that if the conflicting file is added while
Airflow is already
+ running, the collision will not occur until the next restart, making the
root cause
+ difficult to diagnose.
+
Don't use relative imports
..........................
