---
id: dbt-osmosis
version: "1.5.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# dbt-osmosis — A dbt utility for managing YAML to make developing with dbt more delightful.

License: permissive · Maintenance: active · Downloads: 149.7K/mo

## What it is and what it does

dbt-osmosis extends dbt development by automating schema YAML file organization, managing column-level documentation inheritance across dbt lineage, and providing ad-hoc SQL compilation and execution helpers. It ships as a CLI with a Python package interface, centered on four primary surfaces: schema YAML management (organize, document, refactor), documentation inheritance, SQL compile/run helpers, and an optional Streamlit workbench for interactive development. The tool also includes command families for generation, natural-language helpers, schema diffing, migration planning, validation, documentation analysis, SQL linting, and test suggestions.

The package depends on 13 runtime dependencies including dbt-core, dbt-common, dbt-core-interface, click, rich, sqlglot, pyyaml, and others. It targets Python 3.10–3.13 and requires dbt-core 1.8 or later with a compatible adapter. Optional extras unlock Streamlit workbench features, DuckDB adapter support, LLM-assisted synthesis, Azure AD authentication, and an experimental SQL proxy runtime. No known security vulnerabilities are recorded.

Use it for:

- Automatically organize and refactor schema YAML files across a dbt project to maintain consistent structure and naming conventions.
- Inherit column-level documentation from upstream dbt models down the lineage to reduce documentation duplication.
- Compile and run ad-hoc SQL queries within dbt context without materializing models, for testing and exploration.
- Use the Streamlit workbench for interactive SQL development and model testing during dbt development cycles.
- Analyze documentation coverage and gaps across a dbt project to identify undocumented models and columns.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

dbt-osmosis is a CLI tool and Python package that automates schema YAML management, documentation inheritance, and SQL development workflows for dbt projects.

Yes. dbt-osmosis is actively maintained, has low install friction, carries a permissive Apache-2.0 license, and solves a real pain point in dbt workflows—YAML management and documentation inheritance. It is well-suited for teams using dbt-core 1.8+ who want to reduce manual YAML maintenance and improve documentation consistency. Start with the core yaml commands; optional extras can be added later if needed.

## Install

pip install dbt-osmosis
uv add dbt-osmosis
poetry add dbt-osmosis

## Installing dbt-osmosis

Before you install: Low install friction with a pure-Python wheel. Actively maintained (released 2026-07-05, 40 days ago). Requires dbt-core 1.8+ and a compatible adapter; the package intentionally leaves dbt-core unpinned to allow newer releases, though audited support covers dbt Core 1.8.x through 1.11.x.

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions; suitable for most development and production workflows.

Quickstart:

pip install dbt-osmosis

# Configure in dbt_project.yml:
# models:
#   your_project_name:
#     +dbt-osmosis: "_{model}.yml"

dbt-osmosis yaml refactor --dry-run --check

Requires Python 3.10–3.13, dbt-core 1.8+, and a compatible dbt adapter in your environment.

Verify before relying:

- Whether all optional extras (workbench, duckdb, openai, azure, proxy) are production-ready or experimental.
- Specific adapter compatibility matrix beyond the dbt-core 1.8+ requirement.
- Performance characteristics on large dbt projects with many models and YAML files.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 149.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

dbt yaml management automation, dbt documentation inheritance, dbt schema yaml organization, dbt sql compile helpers, dbt development workflow tools, dbt-ecosystem, yaml-automation, documentation-tooling

[View on SkillFed](https://skillfed.io/packages/dbt-osmosis) · [View on PyPI](https://pypi.org/project/dbt-osmosis/)