# astronomer-cosmos

> Orchestrate your dbt projects in Airflow

- **URL**: https://www.freshcrate.ai/projects/astronomer-cosmos
- **Author**: pypi
- **Category**: Databases
- **Latest version**: `astronomer-cosmos-v1.14.2` (2026-05-21)
- **License**: Unknown
- **Source**: https://github.com/astronomer/astronomer-cosmos
- **Homepage**: https://pypi.org/project/astronomer-cosmos/
- **Language**: Python
- **GitHub**: 1,184 stars, 283 forks
- **Registry**: pypi (`astronomer-cosmos`)
- **Tags**: `airflow`, `apache-airflow`, `astronomer`, `dags`, `dbt`, `dbt-core`, `dbt-fusion`, `pypi`

## Description

.. 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.

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `astronomer-cosmos-v1.14.2` | 2026-05-21 | High | **Behaviour Changes**  These changes adjust observable behaviour of the ``ExecutionMode.WATCHER`` execution mode. None of them break the public Cosmos API, but users relying on undocumented internals (graph wiring assertions, XCom backup Variable names, retry-on-recovery semantics, or retry log format) should review before upgrading.  * ``ExecutionMode.WATCHER`` + ``depends_on_past=True``: when the producer task has   ``depends_on_past=True`` (typically set via ``default_args``), the pro |
| `astronomer-cosmos-v1.14.1` | 2026-04-23 | High | Bug Fixes  * Fix ``ExecutionMode.WATCHER`` producer retry behaviour by @tatiana in #2559 * Prevent watcher producer skip propagating to downstream tasks via gateway task by @johnhoran and @tatiana in #2597 * Keep watcher sensor polling when producer is still running by @pankajkoti in #2592 * Fix circular import error in Cosmos plugin discovery under Astro Runtime by @tatiana in #2538 * Fix ``CosmosRichLogger`` crash on ``None`` log message by @tatiana in #2540 * Enable inlets and outlets |
| `1.14.0` | 2026-04-21 | Low | Imported from PyPI (1.14.0) |
| `astronomer-cosmos-v1.14.1a2` | 2026-04-21 | High | * Fix watcher producer retries behaviour by @tatiana in #2559    - Fixes `ExecutionMode.WATCHER_KUBERNETES` as well  https://github.com/astronomer/astronomer-cosmos/pull/2559 |
| `astronomer-cosmos-v1.14.1a1` | 2026-04-21 | High | * Fix watcher producer retries behaviour by @tatiana in #2559  https://github.com/astronomer/astronomer-cosmos/pull/2559 |
| `astronomer-cosmos-v1.14.0` | 2026-04-07 | Medium | 1.14.0 (2026-04-07) ---------------------  Breaking Changes  * Drop support for Airflow versions earlier than **2.9** by @jedcunningham in #2288 * Fix inclusion of package models and selection/exclusion behavior by @pankajkoti in #2357 * ``ExecutionMode.WATCHER``: The per-node ``*_status`` XCom value is now a dict (``{"status": "<status>", "outlet_uris": [...]}``) instead of a plain string. Any custom code that reads these internal XCom keys directly will need to be updated by @pankajkoti |
| `astronomer-cosmos-v1.14.0a9` | 2026-04-07 | Medium | ## What's Changed  * docs: Updating "Project Policies" to "Policies" in menu bar by @jroachgolf84 in https://github.com/astronomer/astronomer-cosmos/pull/2526 * Enforce zero warnings policy for documentation by @dnskr in https://github.com/astronomer/astronomer-cosmos/pull/2513 * Add Airflow 3.2 in test matrix by @pankajastro and @pankajkoti in https://github.com/astronomer/astronomer-cosmos/pull/2472 * Revert "feat: handle tests for `WATCHER_KUBERNETES` mode (#2529)" by @pankajkoti in http |
| `astronomer-cosmos-v1.14.0a8` | 2026-04-07 | Medium | ## What's Changed * Fix typo in watcher execution mode docs by @evanvolgas in https://github.com/astronomer/astronomer-cosmos/pull/2485 * Fix minor documentation issues by @dnskr in https://github.com/astronomer/astronomer-cosmos/pull/2489 * Add troubleshooting note for dbt debug logs in `ExecutionMode.WATCHER` by @tatiana in https://github.com/astronomer/astronomer-cosmos/pull/2491 * RFC: Add patch for newer versions of amazon provider when running dbt on EKS by @aoelvp94 in https://github. |
| `astronomer-cosmos-v1.14.0a7` | 2026-04-06 | Medium | Cut from: https://github.com/astronomer/astronomer-cosmos/pull/2472 (branch: https://github.com/astronomer/astronomer-cosmos/tree/airflow_3.2) |
| `astronomer-cosmos-v1.14.0a6` | 2026-03-25 | Medium | * Fix ``cosmos_debug_max_memory_mb`` XCom not pushed in Watcher sensor tasks by @tatiana in #2503  On top of the other changes in the `main` branch by the time #2503 was created |

## Citation

- HTML: https://www.freshcrate.ai/projects/astronomer-cosmos
- Markdown: https://www.freshcrate.ai/projects/astronomer-cosmos.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/astronomer-cosmos/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._