astronomer-cosmos turns a dbt project into an Airflow DAG

Each dbt model becomes a task in the Airflow graph

The usual way to combine dbt with Airflow is to wrap a dbt command in a BashOperator and let the whole project run as one opaque task. Cosmos takes the opposite approach. It parses the project and renders one Airflow task per model, grouped into Task Groups, so the DAG graph mirrors the dbt dependency graph. That means the DAG you look at in the Airflow UI shows the same lineage you would see in dbt's docs, and each node inherits the Airflow machinery around it: retries, alerting, and the run history of a model that failed. The benefit list includes turning each dbt model into a task or task group complete with retries, alerting and similar features. The cost is that a large dbt project becomes a large Airflow DAG, and Airflow now has to parse, schedule and keep state for every model rather than for a handful of shell commands.

Configuration moves from dbt profiles to Airflow connections

This is the change that most affects an existing project. Instead of a `profiles.yml` with credentials per environment, Cosmos lets the dbt run use the connections already defined in Airflow. The documentation lists running dbt projects against Airflow connections instead of dbt profiles as the first benefit, which sets the direction clearly. For teams that already maintain a hundred connections in Airflow for every other tool, that removes a parallel configuration system. For a team whose dbt setup is already settled, it inverts the ownership question: the credentials now live in Airflow, and the dbt profile file becomes redundant or partial. Any adapter-specific settings that do not map onto an Airflow connection still have to come from somewhere, and the documentation does not spell out the fallback for those.

dbt gets its own virtual environment inside the Airflow worker

Dependency conflicts are the second big problem Cosmos addresses, and the mechanism is concrete rather than aspirational. dbt and its adapter are installed and run inside a virtual environment created for the task, which isolates them from whatever versions of Python packages the Airflow environment already carries. The package manifest lists `virtualenv` among its runtime dependencies, which is what makes that possible, and the benefit list describes native support for installing and running dbt in a virtual environment to avoid dependency conflicts with Airflow. The price is paid at runtime, since building a virtual environment and installing dbt and the adapter into it takes time on every worker that has not cached one. Airflow environments are usually container images, and whether the environment is built once at image time or repeatedly per task run is a question the documentation leaves to the deployment, with the per-run cost scaling with the number of models in the project.

Tests and upstream ingestion become part of the same graph

Two of the listed benefits are really about the shape of the resulting DAG. Running tests immediately after a model completes means a failed test can stop the downstream models that depend on it, rather than being discovered at the end of a full dbt run. Using Airflow's data-aware scheduling means a model can start as soon as the upstream dataset it depends on has landed, so a dbt model does not have to wait for a nightly dbt schedule to pick it up. Both of these depend on the graph being built at DAG parse time, which is what makes Cosmos more than a wrapper. The openlineage integration common dependency in the manifest is there for a related reason: the package comment states that without it, Airflow datasets and assets do not work, and those are the objects data-aware scheduling relies on. So if you strip that dependency, you lose the asset graph, not just a convenience feature.

Rendering a DAG with the DbtDag class

The entry point is the `DbtDag` class, and the documentation uses the jaffle_shop project as its running example, pointing to a file in the `dev/dags` directory of the repository for the full example. The Getting Started guide lives in the project documentation, and a separate `cosmos-demo` repository holds example DAGs. The package itself is published on PyPI under the name `astronomer-cosmos`, and the repository has no separate install script to run, so the install path is the standard Python package install. The declared runtime dependencies are what a worker will pull in:

dependencies = [
    "aenum",
    "attrs",
    "apache-airflow>=2.9.0",
    "Jinja2>=3.0.0",
    "msgpack",
    "packaging>=22.0",
    "virtualenv",
]

The manifest also requires Python 3.10 or newer, and the package targets Airflow 2.9.0 as a floor. Those two numbers are the first things to check against your Airflow image, because an Airflow image built for an older Python cannot run this package at all.

dbt Fusion support and the adapter extras

Cosmos covers dbt Core and dbt Fusion, which shows in the package metadata: the keyword list names `dbt-core` and `dbt Fusion`, and the optional dependency group `dbt-all` lists the adapter packages the project supports, including dbt-athena, dbt-bigquery, dbt-clickhouse, dbt-duckdb and dbt-databricks. The extras exist so that you install only the adapter you use instead of every adapter in the world, and each of those adapters is a separate optional dependency of this package. Two details in that list are worth knowing. dbt-databricks is pinned away from version 1.9.0, and the comment in the manifest explains that 1.9.0 conflicts with the Pydantic version Airflow requires above 2.7, with a link to the matching issue. That is the kind of constraint that tells you a package is maintained against a real ecosystem rather than a fixed set of versions.

Telemetry, versioning and what the project promises

The project follows Semantic Versioning for releases, and the changelog lives in `CHANGELOG.rst` at the root of the repository. The most recent tagged release is v1.15.1 from 2026-08-04, and the last push to the main branch was on 2026-10-19. The licence is Apache 2.0, with the licence file in the repository root, which is a permissive licence. Two operational notes come out of the project files rather than the feature list. The application and its website collect telemetry that end users can disable, described in `PRIVACY_NOTICE.rst`, and a tracking pixel is included in the README for that purpose. A separate `SECURITY.rst` sets out how to report vulnerabilities. Both are the files to read before a security review, along with the Apache 2.0 terms themselves.

Editorial conclusion

Adopt astronomer-cosmos when your dbt models already need to run on an Airflow schedule alongside other pipelines, and your Airflow environment can carry the Airflow 2.9 or newer baseline. Do not adopt it if you want dbt to keep its own profile files and scheduler, since Cosmos deliberately routes configuration through Airflow connections. Verify first that your dbt adapter has a matching extra under dbt-all, that Python 3.10 or newer is available in your Airflow image, and that the version you pin still supports the dbt Fusion path you intend to use.

Frequently asked questions

Official sources

1. astronomer/astronomer-cosmos on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases