Support a global template_searchpath config option in Airflow
- Dominant language
- Python
- Stars
- 46.9k
- Forks
- 17.8k
- Avg merge
- 2d 7h
- Merged PRs (30d)
- 484
Description
### Description
**Apache Airflow version**
3
**What happened?**
While upgrading to Airflow 3, we restructured our DAGs to follow the recommended best practices — specifically, moving shared SQL templates out of the `dags/` directory and into the `include/` folder.
However, once we made this change, our DAGs could no longer find the SQL files unless we explicitly added a `template_searchpath` argument inside every single DAG definition, pointing to an absolute path like `/usr/local/airflow/include`.
This works functionally, but it's not ideal. It requires every DAG to include the same configuration snippet, which makes the code harder to maintain — especially in projects with many DAGs.
**What you think should happen instead?**
There should be a way to define a default `template_searchpath` globally for the entire Airflow deployment — either in `airflow.cfg` or via an environment variable like `AIRFLOW__CORE__TEMPLATE_SEARCHPATH`. That way, DAG authors wouldn’t need to repeat the same setting in every DAG file just to access shared templates or SQL files.
### Use case/motivation
We want all our DAGs to be able to access SQL files from a common shared director. Right now, each DAG must manually set `template_searchpath` for this to work. Being able to define this path globally at the deployment level would reduce code duplication and simplify DAG authoring across multiple teams and projects.
### Related issues
-
### Are you willing to submit a PR?
- [ ] Yes I am willing to submit a PR!
### Code of Conduct
- [x] I agree to follow this project's [Code of Conduct](https://github.com/apache/airflow/blob/main/CODE_OF_CONDUCT.md)
Contributor guide
Research direction
The issue names airflow.cfg, AIRFLOW__CORE__TEMPLATE_SEARCHPATH, DAG definitions, and shared SQL files; start by tracing how DAG template_searchpath is resolved and how core configuration and environment options are loaded. Done means a deployment-level default makes shared templates available without repeating template_searchpath in each DAG.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- data-engineering
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100