# migrating-airflow-2-to-3

> Claude/Codex skill by [@astronomer](https://omgskills.com/library/astronomer/index.md) · 454 stars · Updated 2026-10-14

Guide for migrating Apache Airflow 2.x projects to Airflow 3.x. Use when the user mentions Airflow 3 migration, upgrade, compatibility issues, breaking changes, or wants to modernize their Airflow codebase. If you detect Airflow 2.x code that needs migration, prompt the user and ask if they want you to help upgrade. Always load this skill as the first step for any migration-related request.

Tags: agentic-workflow, agents, ai, ai-agents, airflow, apache-airflow, claude, cursor, dag, data-engineering, data-pipelines, dbt, llm, mcp, orchestrator, skills, workflow-automation, workflow-management, workflow-orchestration, workflows

## Install

```sh
git clone https://github.com/astronomer/agents /tmp/agents && ln -s /tmp/agents/skills/migrating-airflow-2-to-3 ~/.claude/skills/migrating-airflow-2-to-3
```

## From README

Airflow 2 to 3 Migration This skill helps migrate Airflow 2.x DAG code to Airflow 3.x, focusing on code changes (imports, operators, hooks, context, API ). Important: Before migrating to Airflow 3, strongly recommend upgrading to Airflow 2.11 first, then to at least Airflow 3.0.11 (ideally directly to 3.1). Other upgrade paths would make rollbacks impossible. See: https://www.astronomer.io/docs/astro/airflow3/upgrade-af3\#upgrade-your-airflow-2-deployment-to-airflow-3. Additionally, early 3.0 versions have many bugs - 3.1 provides a much better experience. Migration at a Glance Run Ruff's Airflow migration rules to auto-fix detectable issues (AIR30/AIR301/AIR302/AIR31/AIR311/AIR312). ruff check --preview --select AIR --fix --unsafe-fixes . Scan for remaining issues using the manual search checklist in reference/migration-checklist.md. Focus on: direct metadata DB access, legacy imports, scheduling/context keys, XCom pickling, datasets-to-assets, REST API/auth, plugins, and file paths.

## Links

- HTML page: https://omgskills.com/library/astronomer/agents/migrating-airflow-2-to-3/
- GitHub: https://github.com/astronomer/agents
- Author: [@astronomer](https://omgskills.com/library/astronomer/index.md)

## More from this repo

- [airflow-adapter](https://omgskills.com/library/astronomer/agents/astro-airflow-mcp/dot-claude/skills/airflow-adapter/index.md) — Airflow adapter pattern for v2/v3 API compatibility.
   - [@astronomer](https://omgskills.com/library/astronomer/index.md) · 459 stars
- [airflow-plugins](https://omgskills.com/library/astronomer/agents/skills/airflow-plugins/index.md) — Builds Airflow 3.1+ plugins that embed FastAPI apps, custom UI pages, React components, middleware, macros, and...
   - [@astronomer](https://omgskills.com/library/astronomer/index.md) · 459 stars
- [analyzing-data](https://omgskills.com/library/astronomer/agents/skills/analyzing-data/index.md) — Queries the data warehouse with SQL and answers business questions about data.
   - [@astronomer](https://omgskills.com/library/astronomer/index.md) · 459 stars