Checking DAGs for Airflow 3 with Ruff AIR rules

The more DAG files and custom operators a repository holds, the more findings Ruff reports and the more code a team must read, triage and test. Each AIR finding needs a decision: apply the automatic rewrite, change the code by hand, or confirm the finding does not apply. A repository with a few dozen DAGs and little custom code usually clears in a short cycle, while one with hundreds of DAGs and many custom operators spreads the same triage across more files and more owners. Count your DAG files, operator classes and hook subclasses first, since that count sets the size of the review queue. Ask any partner quoting the work to base its estimate on that inventory from your own repository.

Dynamic DAG generation builds tasks from configuration files, loops, database queries or external APIs, so Ruff sees only the code that builds the DAG and not every task it produces. A rule can pass on the source file while the generated tasks still import removed modules or use removed context keys. Reviewers then have to run the parser and inspect generated output, which adds test time. Teams with heavy generation should plan to render DAGs in a test environment and compare the task lists before and after the upgrade.

Task code that opens Airflow database sessions or imports Airflow models cannot keep working unchanged in Airflow 3, and the upgrade guide directs that work to the REST API or Task SDK. Ruff can flag some of these imports, but it cannot tell you what the code was trying to achieve. Each case needs a design decision, a rewrite and a test against a real run, which usually takes longer than a mechanical import change. Search your repository for airflow.models, airflow.settings and Session usage, and group the results by purpose, such as reading run state, writing audit rows or cleaning up history.

SubDAGs are removed in Airflow 3 in favor of TaskGroups, so every SubDagOperator needs a rewrite rather than a rename. Ruff can point to the usage, but the decision about whether a TaskGroup, an asset-based dependency or a separate DAG fits the job belongs to the team that owns the pipeline. Task IDs can change during the rewrite, which affects run history and any downstream references, so each rewritten DAG needs a comparison test. Count the SubDAG usages early, because each one adds a design decision and a regression check.

Plugins and UI code are reviewed differently from DAG files because they depend on the Airflow web layer, which changed in Airflow 3. Flask AppBuilder views, menu items, blueprints and custom security manager imports may not be covered by the DAG rules at all, so they need a separate inventory and review. Ruff can help with DAG code, but plugin work often requires framework changes, UI tests and access checks. Count plugins, custom views and any webserver_config.py overrides before planning the review, since each one can require work outside the DAG repository.

Each owning team reviews its own DAGs, decides how to handle its findings and signs off on its tests, so the total time grows with the number of teams even when the code volume is modest. Shared operators and common libraries add another layer, because a fix in one shared module can change behavior for every team that imports it. Map DAG directories to owners, agree who approves automatic rewrites, and set a single date for shared code to be reviewed first. Ownership gaps are a common cause of stalled findings.

The figures come from your own repository, not from a general rule of thumb. Run Ruff with the AIR rules against a copy of the repository and record the number of findings by rule, by directory and by owner. Then count DAG files, dynamically generated DAGs, custom operators, metadata database calls, SubDAG usages and plugins. Those counts give a planning baseline that a partner or internal team can use to scope the work in writing, and they show which drivers dominate your effort.

Yes, in most cases. Ruff is a standalone linter, and the AIR rules run against your DAG files without a running Airflow environment, so a developer or platform engineer can run it from a workstation or a CI job. The work that usually needs outside help is not the scan itself but deciding what to do with the findings: which fixes to accept, which DAGs depend on removed behavior, and how to sequence changes across several teams. Confirm your Ruff version with the upgrade guide first, since the guide recommends Ruff 0.13.1 or later for these rules.

Setup for a single repository is usually short, because it means installing a pinned Ruff version, selecting the AIR rules and running the check. The effort grows with the number of repositories, the amount of custom code that imports Airflow internals, and how many DAGs depend on removed features such as SubDAGs or legacy context keys. Ask your team to count DAG repositories, plugins and shared libraries before estimating, and ask any partner for a quote built from that written inventory rather than from a generic figure.

Not without review. Ruff applies safe fixes with the --fix option, and the --unsafe-fixes option applies rewrites that can change behavior in edge cases. Treat every unsafe fix as a code change that needs a test run and a diff review. Keep them in a separate commit, run the DAG test suite, and confirm that task IDs, schedules and imports still behave as before. Automated rewrites do not cover behavior that depends on runtime state, so manual review is still required for those cases.

No. The AIR301 and AIR302 checks are designed to find breaking changes in your DAG code regardless of the Airflow 2 patch you run. The Airflow 3 upgrade guide requires being on Airflow 2.7 or later before the upgrade itself, and it recommends moving to the latest 2.x line first. Running Ruff on your current code is useful early because it shows the work size. Whether you stop at 2.11 as an intermediate step is a planning decision that depends on your provider packages and maintenance window.

Developers need to own the DAG code, know which operators and imports each pipeline uses, and review the changes the check proposes. The platform team needs to provide a CI runner with network access to the package index, a pinned Ruff version, a branch or environment where the changes can be tested, and access to the repositories. Both groups should agree on who approves unsafe fixes and who signs off that a DAG is ready for the Airflow 3 scheduler.

It makes the timing more pressing. Airflow 2 entered limited maintenance on October 22, 2025 and reached end of life on April 22, 2026, after which it gets no fixes. Limited maintenance covers only security and critical bug fixes, so teams still on 2.x should plan a move rather than wait. Running the Ruff check early gives you a measured list of changes that feeds into that plan. Confirm with your security team how long your current 2.x deployment can remain in service under your own policies.

No. The AIR rules catch known import paths, removed features and renamed APIs that can be detected statically. They cannot see runtime behavior, such as a task that reads the metadata database through a session, a custom plugin that depends on the Flask AppBuilder UI, or a provider operator whose parameters changed. Use the check as the first gate in CI, then run DAGs in a staging environment with a representative Airflow 3 deployment before cutover.