Why upgrade to Airflow 2.11 before moving to Airflow 3
If your self-hosted estate runs Airflow 2.x and must reach Airflow 3, the upgrade guide requires you to be on Airflow 2.7 or later before you upgrade, and it recommends moving to the latest 2.x release first. Airflow 2.11 is the last Airflow 2 line, so it is the target for this stage. Treat it as a stepping stone rather than a place to stay: the Airflow 2 current patch, 2.11.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 every month on 2.11 after that date is a month of narrowing support.
Before you change the Airflow version, confirm which release each environment runs today, including schedulers, workers, the API server or webserver, and any images or Helm releases that pin a tag. Check the version life cycle table against the dates above, and record which team owns the decision to move each environment. Estates with 2.7 or older must step through intermediate 2.x releases, so plan those hops in separate change windows with their own rollback points.
Set a dated target for leaving 2.11, and make it a decision your leadership signs off. Your plan should state whether you will move to Airflow 3 directly after 2.11 or hold 2.11 for a short period while DAG code, providers and the metadata database are prepared. Ask your team and any managed service vendor how long they will keep 2.11 available, because managed offerings can set their own timelines. Any extension beyond April 22, 2026 carries the risk of running an end-of-life release without fixes.
Which changes hit you on 2.x before the Airflow 3 cutover
This table lists the changes that matter while you are still running Airflow 2.x, with the impact of each and the action to take now. Read each row as a pre-cutover task: the first rows set the version floor, the middle rows cover code and provider work, and the last row sets the support deadline that bounds how long 2.11 can stay in production.
| Change | Impact on your 2.x estate | Action before cutover |
|---|---|---|
| Minimum version to upgrade from | The Airflow 3 upgrade guide requires being on Airflow 2.7 or later, so older 2.x installs cannot upgrade directly. | Confirm your current 2.x version. If it is below 2.7, plan an intermediate upgrade first, then move to the latest 2.x. |
| Latest 2.x recommended first | The guide recommends moving to the latest 2.x release before Airflow 3, which for this page is the 2.11 line. | Upgrade to 2.11 in staging, run your DAG tests, then promote to production. |
| Standard provider split | BashOperator, PythonOperator, ExternalTaskSensor and FileSensor move into apache-airflow-providers-standard, which can already be installed on 2.x. | Install apache-airflow-providers-standard on 2.x and switch imports now, so the change is tested while you can still roll back. |
| AIR301 and AIR302 breaking-change rules | These Ruff rules flag code that will fail or behave differently on Airflow 3. | Run Ruff checks across the DAG repository on 2.x and fix every flagged breaking change before the cutover. |
| AIR311 and AIR312 recommended updates | These rules flag non-breaking changes that Airflow 3 expects you to adopt. | Review the findings and apply them where the code path is covered by tests. |
| Ruff 0.13.1 or later with --fix and --unsafe-fixes | Older Ruff versions may not include the AIR rules described in the upgrade guide. The unsafe fix option can change code behavior. | Pin Ruff to 0.13.1 or later, use --fix for safe rewrites, and review every --unsafe-fixes change manually. |
| Airflow 2 end of life | Airflow 2 entered limited maintenance on October 22, 2025 and reached end of life on April 22, 2026, after which it gets no fixes. | Set a dated cutover plan. Confirm with your security team how long 2.11 can run in production and what compensating controls apply after April 22, 2026. |
How to sequence the move from 2.x to 2.11 to 3.x
This sequence takes an Airflow 2 deployment from its current release to 2.11, the last 2.x line, while keeping each change reversible. It ends with DAGs that parse, run and pass Ruff AIR checks, so the Airflow 3 cutover becomes a separate, scoped decision.
Confirm the starting version is 2.7 or later
The platform owner records the Airflow version on every component that runs DAG code or serves the UI, including the scheduler, workers, API or webserver and any DAG processor. Running
airflow versionin each environment and checking container image tags is usually enough. The Airflow 3 upgrade guide requires a starting point of 2.7 or later. If any environment sits below 2.7, move it to 2.7 or later as a separate change and repeat this check. The step is done when one inventory lists every environment with its exact version. Rollback point: none is needed, because this step only reads state.Back up the metadata database
The database owner takes a consistent backup of the Airflow metadata database before any package or image changes. The production deployment guide recommends PostgreSQL or MySQL and warns that the default SQLite backend is for testing only and can lose data in production. If you still run SQLite, move to a supported database before relying on this backup. Restore the backup into a separate instance and confirm that DAG runs and task history load correctly. The step is done when the restore test succeeds and the backup identifier is written into the change record. Rollback point: this backup is the fallback for the database migration in a later step.
Install the standard provider on 2.x
The platform team installs
apache-airflow-providers-standardinto the current 2.x environment, pinned to a version that matches the installed Airflow release. This package holds BashOperator, PythonOperator, ExternalTaskSensor and FileSensor, which moved out of airflow-core for Airflow 3 and can also be installed on Airflow 2.x. Update DAG imports so these operators load from the provider package, then parse every DAG in a test environment. The step is done when all DAGs parse without import errors on the current 2.x release. Rollback point: restore the previous requirements file and image tag, since this change touches only the environment and not the metadata database.Run Ruff AIR checks and apply safe fixes
The DAG repository owner runs Ruff 0.13.1 or later with the AIR rules. AIR301 and AIR302 flag breaking changes, while AIR311 and AIR312 flag recommended non-breaking updates. Start with
ruff check --select AIRto review every finding, then apply only the automatic safe fixes with--fix. Review each rewrite produced by--unsafe-fixesas its own diff before accepting it. The step is done when the safe fixes are committed and every remaining finding is listed in the change record with an owner. Rollback point: revert the commit that holds the fixes, since the code changes are isolated in version control.Upgrade the Airflow components to 2.11
The platform team upgrades the scheduler, workers and web components to the 2.11 line, where 2.11.2 is the current patch release. Upgrade all components in one window so they run the same release. Then run
airflow db migrateagainst the database that was backed up earlier and read the migration output closely. The step is done when the migration completes and every component reports the same 2.11 patch. Container and Helm chart specifics for Kubernetes are covered on later Airflow 3 pages. Rollback point: restore the database from the backup and redeploy the previous image, because an older release may not run correctly against a migrated database.Verify DAG parsing and runs on 2.11
The operations team checks import errors, scheduler heartbeats and recent DAG runs on the 2.11 deployment. Then it runs a representative set of DAGs and compares task outcomes with the baseline recorded before the upgrade. Include DAGs that use operators from the standard provider, sensors that wait on other DAGs or files, and tasks that read Airflow data directly. Watch scheduler and worker logs through at least one full schedule cycle for each critical pipeline. The step is done when parsing is clean, critical pipelines match their baseline outcomes, and the sign-off is recorded. Rollback point: if verification fails, restore the step 2 backup and the previous image, and keep the code and provider changes in version control.
Decide the Airflow 3 cutover
Engineering leadership and the platform owner make a written go or no-go decision for Airflow 3. The decision should cover the remaining Airflow 3 work, including the API server replacing the webserver, the DAG processor running as its own component, removed features such as SubDAGs, and the Helm chart if you run on Kubernetes. Check the version life cycle table to confirm which 2.x line still receives fixes before you set a date. The step is done when the decision, its owner and the fallback plan are recorded. Rollback point: 2.11 with the step 2 backup remains the fallback until the Airflow 3 cutover is verified.
How long Airflow 2.11 can stay in production
The key distinction is between limited maintenance and end of life. Airflow 2 (current patch 2.11.2) entered limited maintenance on October 22, 2025, when it received security and critical bug fixes only. It reached end of life on April 22, 2026, and from that date it gets no fixes at all. A security issue found in Airflow 2.11 after that date will not be patched upstream, so any remediation falls to your own team or a partner. Confirm with your security owner whether the current patch level is the one you intend to run and who is responsible for watching the version life cycle and the project's advisories.
The exposure depends on where Airflow runs. A deployment with an internet-reachable webserver or API, shared access by many teams, or regulated data flowing through its tasks carries more risk from an unpatched core than an internal, tightly restricted instance. Ask your security and compliance owners to record a formal risk acceptance for running 2.11 after end of life, including the compensating controls (network restrictions, reduced access, enhanced logging) and a review date. Provider packages are the second pressure point: as the core moves on, providers and the libraries they depend on will drop support for older Airflow 2 lines, so a provider upgrade you need for a connector may stop being installable on 2.11 without a core upgrade.
The trade-off is between a fast move to Airflow 3 and a planned one. A fast move reduces the window of unpatched exposure but compresses DAG remediation, testing and stakeholder sign-off into a shorter period. A planned move gives time to run Ruff AIR checks, fix DAGs and rehearse the metadata database migration, but it extends the time on an unsupported line. Many teams split the difference by fixing the highest-risk instances first and keeping a dated plan for the rest. Whichever path you choose, put the end-of-life date and the risk acceptance in your change records so the decision is auditable.
What to prepare before the Airflow 2.11 upgrade
Moving to Airflow 2.11 is a short, controlled step on the way to Airflow 3, not a routine patch. The cards below cover the artifacts and decisions that make that step reversible: a tested database backup, a complete picture of what runs on the scheduler, a provider baseline, a staging copy of the production topology and a rollback plan with named owners.
Verified metadata database backup
Take a backup of the Airflow metadata database before any change, and confirm it restores. Airflow's production guidance warns that the default SQLite backend is for testing only and can lose data in production, so the backup target should be PostgreSQL or MySQL. Check that the backup covers the schema, not only the data, and record the Airflow version it came from. Ask your DBA to restore it into a scratch instance and run a simple query against DAG runs and task instances.
Inventory of DAGs and custom code
List every DAG file, custom operator, sensor, hook and plugin in the repository, along with the owner and the last run date of each. Mark which items are still scheduled and which are dormant, since dormant DAGs are often the ones that break later. Include plugins that add UI views or menu items, because those depend on Flask AppBuilder and will need separate work for Airflow 3. This inventory becomes the input for the Ruff AIR checks you run on 2.x.
Provider packages and pinned versions
Record every installed provider package with its exact version, and whether it is pinned in a constraints file or installed loosely. Note which providers your DAGs import directly. The standard provider holds operators such as BashOperator and PythonOperator, and it can be installed on Airflow 2.x ahead of the move. Confirm the minimum Airflow version each provider requires before you change anything, so the upgrade does not pull in a package your current core cannot run.
Staging environment that mirrors production
Build a staging environment with the same scheduler count, executor type, worker topology and database engine as production. Airflow supports running more than one scheduler against the same database, so a single-scheduler staging system can hide locking and ordering problems. Use the same container image or installation method, and replay a representative set of DAG runs, including sensors and long-running tasks. Staging results only count if the topology matches.
Rollback plan with named owners
Write the rollback steps before the change window opens. Name one person who can stop the upgrade, one who restores the database, and one who reverts the image or package version and checks scheduler health. Define the trigger conditions in advance, such as DAG runs that stop being scheduled or task instances that fail to start. Agree who communicates with the teams that own pipelines. Because Airflow 2 reaches end of life on April 22, 2026, a rollback should return you to a supported 2.11 state, not an unsupported release.
How the upgrade differs by executor and deployment
On virtual machines, the 2.11 step is mostly about the components you run yourself. Plan the scheduler, webserver, DAG processor and workers as one set of versions, because you will upgrade the Airflow core, the providers and the Python environment together. Airflow 3 splits the webserver into an API server and requires the DAG processor to run as its own component, so a VM host that bundles everything into one service needs a new layout before the 3.x cutover. The metadata database must be PostgreSQL or MySQL, since SQLite is for testing only.
- Process layout: List every scheduler, webserver and worker service and note which ones share a host or a virtualenv.
- Celery broker and result backend: Confirm the broker version and the result backend are supported by the 2.11 line and plan any changes before the upgrade window.
- Multiple schedulers: If you already run more than one scheduler, confirm the database locking and failover behavior on 2.11 in your environment.
- Worker environments: Check that each worker image or virtualenv pins the same provider versions as the scheduler.
- Standard provider: Install the standard provider on 2.11 early so BashOperator, PythonOperator and the sensors resolve the same way they will in Airflow 3.
Confirm your current executor and every service placement with the team that runs the VMs before you choose the 2.11 target.
On Kubernetes, the official Helm chart and the official Docker image define most of the upgrade path. The chart values map the webserver, scheduler, workers and DAG processor, so a 2.11 release should be tested as a separate chart release in staging before the production values change. Use container images for the Airflow version you are moving to, and keep the chart and image versions in step. The chart upgrade to Airflow 3 changes how the API server and DAG processor are configured, so the 2.11 step is the point to confirm that your values files and GitOps pipeline can express those settings.
- Chart and image pairing: Record the chart version and image tag for the current release and for the 2.11 target.
- Executor values: Review the KubernetesExecutor or CeleryExecutor settings inside the chart values, not only the image tag.
- Migration jobs: Check how database migration runs under your GitOps tool so it does not race with a rolling restart.
- Staging release: Run the 2.11 chart upgrade in a separate release name with a copy of the metadata database.
- Cluster versions: Confirm the Kubernetes version against the Airflow 3.3.2 prerequisites before you plan the later Airflow 3 move.
Check the chart and image versions against the Helm chart documentation for your target release before you change production values.
Since Airflow 2.10.0, one deployment can run several executors, and many teams use this to send some tasks to Celery workers and others to Kubernetes pods. This is the group most likely to need a redesign before Airflow 3. The hybrid CeleryKubernetesExecutor and LocalKubernetesExecutor are no longer supported as of Airflow 3.0.0, so if your DAGs or configuration select either of them, flag that now and plan how those tasks will move to a supported executor configuration. Keep the list of executor choices per DAG or queue so the migration does not depend on memory.
- Hybrid executors: Find every use of CeleryKubernetesExecutor and LocalKubernetesExecutor in configuration and DAG code and record it as a blocker for 3.0.0.
- Executor routing: List which tasks run on which executor and how they are selected, such as queue names or executor fields on tasks.
- Test coverage: Run tasks on each executor path on 2.11 so you can compare behavior before and after the change.
- Worker sizing: Confirm capacity for each executor pool, since running several executors often splits load across separate systems.
- Ownership: Name the team that owns each executor path so changes are reviewed together.
Confirm your executor choice for every environment against your own configuration and the executor documentation before you commit to a 2.11 plan.
What makes the 2.11 upgrade take longer
This table lists the factors that change how much work the move to Airflow 2.11 involves, with the effect each one has and how to keep it manageable. Read it before estimating scope, because the largest drivers are usually the DAG codebase and the number of environments that must be promoted in order.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Number of DAGs and custom operators | Every DAG and custom operator must be checked, and custom operators may import Airflow internals that changed between 2.x releases | Inventory DAG repositories first and group code by owner so checks run in batches |
| AIR301 and AIR302 findings | Each finding is a code path that depends on a removed or changed feature and must be rewritten or confirmed as safe | Run Ruff AIR checks on the 2.x codebase early and apply only the fixes you can review |
| Custom plugins and UI extensions | Plugins tied to Flask AppBuilder views or webserver customizations need separate testing on 2.x and later porting | List every plugin and its hooks before scoping, and note which ones the team still uses |
| Database size and history retention | Large metadata databases take longer to back up, migrate and test, and extended history slows UI and queries | Agree a retention window and trim history under a tested backup before the upgrade window |
| Number of providers and their versions | Each provider has its own minimum Airflow version and operator changes, so mismatches surface as import or runtime failures | Pin provider versions in a constraint file and upgrade providers on a separate, tested cadence |
| Multi-executor setups | Mixed executors such as Celery and Kubernetes add worker images, queues and configuration that must agree across the deployment | Document which executor runs which DAGs and test each one in staging |
| Environments promoted in sequence | Development, staging and production each need the same tested changes, and a fix in one environment often has to be repeated in the next | Keep environment configuration in version control so each promotion repeats the same steps |
| Custom code that uses the metadata database | Direct database access in DAG or task code is a separate rewrite target before Airflow 3 and affects how the 2.x code is tested | Find these call sites with code search and record each one with its intended replacement |
Questions buyers ask about the Airflow 2.11 upgrade
What does the Airflow 2.11 upgrade cost and what drives the fee?
The fee follows from the written scope, not from a list price, because DeployOpen does not publish one. The main drivers are how many DAG repositories and environments need work, how many custom operators, plugins and connections the code depends on, whether the Ruff AIR checks surface large rewrites, and how many non-production environments must be upgraded and verified. Each engagement is fixed-scope, so the quote should list the environments, repositories, deliverables and the verification steps agreed in writing before work starts. Ask whether the quote covers the Helm chart or Kubernetes changes separately, and whether ongoing support is a separate retainer. Ask for the cost of any follow-on Airflow 3 work so the two phases are priced side by side.
How long does an Airflow 2.11 upgrade take?
Duration depends on the size and condition of the existing estate, which is why no fixed timeline is given here. The factors that set it are the number of DAGs and teams involved, how many DAGs need code changes after the Ruff scan, the state of the metadata database and its backup window, the number of environments that must move in sequence, and how quickly your change approval process runs. Lead time for staging access and for DAG owners to review changes often matters as much as the technical work. Ask for a timeline in the written scope that names each environment, the review gates and the cutover window, and ask what happens if a DAG owner review takes longer than planned.
Can our own team upgrade Airflow to 2.11 without a partner?
Yes, a team that already runs Airflow 2 in production can usually do this upgrade in-house, and the upgrade guide sets out the prerequisites. The team needs someone who can run the Ruff AIR checks, read the results, install the standard provider package on 2.x, test DAGs in staging and coordinate the database migration. The questions to answer honestly are whether you have that skill on hand, whether anyone can own the rollback plan, and whether the team has time alongside its normal work. Many organizations split the work: internal teams own DAG changes while a partner plans the sequence, runs the metadata database backup and migration checks, and documents the evidence. Confirm your own capacity before deciding.
What do we need to provide during an Airflow 2.11 upgrade?
The work depends on access and people more than on tooling. You will need access to the Airflow source repositories, the Airflow environments in each stage, the metadata database and its backups, and the container image or virtual machine build pipeline. You also need named DAG owners who can review changes and confirm behavior, a staging environment that resembles production, and an agreed change window with your operations and change advisory teams. Ask your team to list every provider connection, secret backend and custom plugin in use before work starts, because these shape testing. Expect to provide sign-off on each stage in writing.
Is Airflow 2.11 safe to run after April 22, 2026?
Airflow 2 reached end of life on April 22, 2026, and after that date the project provides no fixes, so 2.11 receives no security patches from the Airflow project. Under the support policy, limited maintenance covered only security and critical bug fixes, and that window began on October 22, 2025. Running an end-of-life release is a risk decision that your security and compliance teams must document, including compensating controls and any planned exit date. Teams that continue to run 2.11 should ask whether their managed service or vendor offers extended support, and confirm that answer in writing. Check the version life cycle page for the current status before making the decision.
Can we apply Ruff AIR fixes to DAG code without a review?
No, the safe fixes are only a starting point and should be reviewed before merge. Ruff's AIR rules flag breaking changes under AIR301 and AIR302 and recommended non-breaking updates under AIR311 and AIR312. The --fix option applies safe automatic rewrites, while --unsafe-fixes applies rewrites that may change behavior. Treat every change from --unsafe-fixes as a code change that needs a DAG owner's review and a test run in staging. Keep the Ruff version pinned to the release the upgrade guide recommends (0.13.1 or later), run the check in CI, and store the output as evidence of the review. Ask your partner or internal lead how each rule category maps to your repositories before running any fix.
Do we need to move to Airflow 2.11 before Airflow 3?
The Airflow 3 upgrade guide requires being on Airflow 2.7 or later before upgrading, and it recommends moving to the latest 2.x release first. Moving to 2.11 is therefore the recommended stepping stone for most teams, and it lets you run the Ruff AIR checks and install the standard provider package while your production system is still on a supported Airflow 2 line. If you are already on 2.7 or later, the decision is about timing and risk rather than a technical blocker. Confirm your current version and check the upgrade guide before planning the sequence.
What DeployOpen delivers for a 2.11 stepping-stone upgrade
DeployOpen delivers the 2.11 stepping-stone upgrade as a fixed-scope engagement with a defined set of artifacts. The first is an inventory of the running Airflow 2 environment: the Airflow and provider versions in use, the executor and metadata database, how DAGs are delivered, which auth manager is configured, and which DAGs depend on removed or changed features. The second is an AIR check report from Ruff run across the DAG repository, listing AIR301 and AIR302 breaking findings and AIR311 and AIR312 recommended updates, with each finding tied to a file, a owner and a proposed fix. The third is a provider and constraint plan that sets the target versions, notes the standard provider package and records which constraint file each environment will use.
The remaining deliverables cover the change itself. DeployOpen writes a staged upgrade runbook that moves a non-production environment first, then production, with the database backup, the migration command, the verification steps and the rollback path written out for each stage. Backup and rollback evidence records what was captured before each change and whether a restore was tested. Handover documentation describes the final state, the open findings, and what your team needs to watch during the period 2.11 stays in production. Your team should confirm which of these artifacts it needs in what format, since the exact list is set during scoping.
Scope, deliverables and timeline are agreed in writing before work starts, so the quote follows from the environments, DAG count and integrations you bring into scope. Ongoing support, including security patch review for the 2.x line and later upgrade work toward Airflow 3, is available as a retainer. Ask for the written scope to name which Airflow 2 environments are included, who approves each cutover, and how findings that need code changes by your DAG authors are tracked to closure.
How DeployOpen works on this
DeployOpen plans and runs the move to Airflow 2.11 inside your own infrastructure, starting from a written scope that names the environments, DAG repositories and cutover window. The work is delivered in the same order as the checks described above, so each step leaves evidence your team can review.
How we scope
- The written scope lists which Airflow 2.x environments, DAG repositories and deployment methods the 2.11 upgrade covers.
- We confirm the current Airflow 2 patch level and whether your target is a 2.11 line that receives only security and critical fixes.
- Engagements are fixed-scope, so deliverables, timelines and responsibilities are agreed in writing before work starts.
How we build
- We run Ruff AIR checks against your DAG code and record which findings are fixed, deferred or accepted.
- We install and pin the standard provider package on 2.x in staging, then test operators such as BashOperator and PythonOperator.
- We rehearse the database migration and rollback on a copy of your metadata database before any production change.
How we hand over
- You receive version-pinned configuration, constraint files and the upgrade runbook for each environment in scope.
- Test results, Ruff reports and the list of open findings are handed over with named owners and dates in the scope.
- Our team walks your engineers through the cutover steps and the planned Airflow 3 path so your staff can run the next stage.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after the handover.
- Retainer scope, response expectations and fees are set out in a separate written agreement, so confirm them during the quote.
- Ask for the retainer terms to cover tracking of the Airflow 2 end of life date and the planned move to Airflow 3.
