README.rst

March 5, 2026 · View on GitHub

.. License badge .. |license| image:: https://img.shields.io/:license-Apache%202-blue.svg :target: https://www.apache.org/licenses/LICENSE-2.0.txt :alt: License

.. PyPI badges .. |fury| image:: https://badge.fury.io/py/astronomer-cosmos.svg :target: https://badge.fury.io/py/astronomer-cosmos :alt: PyPI version

.. |python| image:: https://img.shields.io/pypi/pyversions/astronomer-cosmos.svg :target: https://pypi.org/project/astronomer-cosmos/ :alt: Python versions

.. |downloads| image:: https://img.shields.io/pypi/dm/astronomer-cosmos :target: https://pypi.org/project/astronomer-cosmos/ :alt: PyPI downloads

.. Community badges .. |contributors| image:: https://img.shields.io/github/contributors/astronomer/astronomer-cosmos :target: https://github.com/astronomer/astronomer-cosmos/graphs/contributors :alt: Contributors

.. |commits| image:: https://img.shields.io/github/commit-activity/m/astronomer/astronomer-cosmos :target: https://github.com/astronomer/astronomer-cosmos/commits/main :alt: Commit activity

.. |slack| image:: https://img.shields.io/badge/slack-%23airflow--dbt-white.svg?logo=slack&style=social :target: https://join.slack.com/t/apache-airflow/shared_invite/zt-1zy8e8h85-es~fn19iMzUmkhPwnyRT6Q :alt: Slack #airflow-dbt

.. |health| image:: https://insights.linuxfoundation.org/api/badge/health-score?project=astronomer-astronomer-cosmos :target: https://insights.linuxfoundation.org/project/astronomer-astronomer-cosmos :alt: LFX Health Score

.. Dev tools badges .. |pre-commit| image:: https://results.pre-commit.ci/badge/github/astronomer/astronomer-cosmos/main.svg :target: https://results.pre-commit.ci/latest/github/astronomer/astronomer-cosmos/main :alt: pre-commit.ci status

.. Build status badges .. |build-main| image:: https://github.com/astronomer/astronomer-cosmos/actions/workflows/test.yml/badge.svg :target: https://github.com/astronomer/astronomer-cosmos/actions :alt: Build main

.. image:: https://raw.githubusercontent.com/astronomer/astronomer-cosmos/main/docs/_static/cosmos-logo.svg

===========================================================

|license| |fury| |python| |downloads|

|contributors| |commits| |slack| |health|

|pre-commit| |build-main|

Run your dbt Core projects as Apache Airflow® <https://airflow.apache.org/>_ DAGs and Task Groups with a few lines of code. Benefits include:

  • Run dbt projects against Airflow connections instead of dbt profiles
  • Native support for installing and running dbt in a virtual environment to avoid dependency conflicts with Airflow
  • Run tests immediately after a model is done to catch issues early
  • Utilize Airflow's data-aware scheduling to run models immediately after upstream ingestion
  • Turn each dbt model into a task/task group complete with retries, alerting, etc.

Quickstart

Check out the Getting Started guide on our docs <https://astronomer.github.io/astronomer-cosmos/getting_started/index.html>. See more examples at /dev/dags <https://github.com/astronomer/astronomer-cosmos/tree/main/dev/dags> and at the cosmos-demo repo <https://github.com/astronomer/cosmos-demo>_.

Example Usage

You can render a Cosmos Airflow DAG using the DbtDag class. Here's an example with the jaffle_shop project <https://github.com/dbt-labs/jaffle_shop>_:

.. This renders on Github but not Sphinx:

https://github.com/astronomer/astronomer-cosmos/blob/24aa38e528e299ef51ca6baf32f5a6185887d432/dev/dags/basic_cosmos_dag.py#L1-L42

This will generate an Airflow DAG that looks like this:

.. figure:: https://github.com/astronomer/astronomer-cosmos/blob/main/docs/_static/jaffle_shop_dag.png

Community

  • Join us on the Airflow Slack <https://join.slack.com/t/apache-airflow/shared_invite/zt-1zy8e8h85-es~fn19iMzUmkhPwnyRT6Q>_ at #airflow-dbt

Changelog

We follow Semantic Versioning <https://semver.org/>_ for releases. Check CHANGELOG.rst <https://github.com/astronomer/astronomer-cosmos/blob/main/CHANGELOG.rst>_ for the latest changes.

Contributing Guide

All contributions, bug reports, bug fixes, documentation improvements, enhancements are welcome.

A detailed overview an how to contribute can be found in the Contributing Guide <https://astronomer.github.io/astronomer-cosmos/policy/contributing>_.

As contributors and maintainers to this project, you are expected to abide by the Contributor Code of Conduct <https://github.com/astronomer/astronomer-cosmos/blob/main/CODE_OF_CONDUCT.md>_.

License

Apache License 2.0 <https://github.com/astronomer/astronomer-cosmos/blob/main/LICENSE>_

Privacy Notice

The application and this website collect telemetry to support the project's development. These can be disabled by the end-users.

Read the Privacy Notice <https://github.com/astronomer/astronomer-cosmos/blob/main/PRIVACY_NOTICE.rst>_ to learn more about it.

.. Tracking pixel for Scarf

.. image:: https://static.scarf.sh/a.png?x-pxid=ae43a92a-5a21-4c77-af8b-99c2242adf93 :target: https://static.scarf.sh/a.png?x-pxid=ae43a92a-5a21-4c77-af8b-99c2242adf93

Related Repositories

The core Astronomer Cosmos library is developed in this repository (astronomer-cosmos <https://github.com/astronomer/astronomer-cosmos>_). The following additional repositories are maintained as part of the Astronomer Cosmos project:

  • cosmos-demo <https://github.com/astronomer/cosmos-demo>_ - Example DAGs and demo project for Cosmos

At this time, Cosmos has no other subprojects or additional repositories beyond the one listed above.

Security Policy

Check the project's Security Policy <https://github.com/astronomer/astronomer-cosmos/blob/main/SECURITY.rst>_ to learn how to report security vulnerabilities in Astronomer Cosmos and how security issues reported to the Astronomer Cosmos security team are handled.