apache / apache/airflow

Support a global template_searchpath config option in Airflow

Open
#53,972 10 comments 0 reactions 0 assignees View on GitHub
area:core kind:feature needs-triage
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.