Skip to main content

Installation

Pick the installation approach that matches your workflow. All examples assume you install a dbt adapter alongside dbt-osmosis.

dbt-osmosis keeps its package support open for dbt Core 1.8+.

Audited blocking support covers dbt Core 1.8.x through 1.11.x in CI. The package metadata intentionally remains dbt-core>=1.8 without an upper bound so installers can resolve newer dbt releases. Future dbt Core minors are canary-only until explicitly audited; scheduled/manual canary CI uses unpinned latest dbt-core and dbt-duckdb to make upstream breakage visible without redefining audited support. Install a dbt adapter version that is compatible with the dbt Core runtime in your environment; adapter compatibility is owned by the adapter and dbt Core pairing, not by dbt-osmosis extras.

uv tool install --with="dbt-<adapter>" dbt-osmosis

This creates an isolated tool environment and exposes the dbt-osmosis command globally.

Run with uvx (ephemeral)​

uvx --with="dbt-<adapter>" dbt-osmosis --help

Use uvx when you want a one-off run without installing the tool globally.

Install with pip​

pip install "dbt-osmosis" "dbt-<adapter>"

This installs into the active Python environment (virtualenv, venv, or system Python).

Optional extras​

  • dbt-osmosis[workbench] installs the Streamlit workbench UI dependencies.
  • dbt-osmosis[duckdb] installs the DuckDB adapter used by the demo project and fixture workflows.
  • dbt-osmosis[openai] installs the OpenAI SDK for synthesis, natural-language generation, test-llm, and AI test suggestions. If LLM_PROVIDER is unset, these commands default to the OpenAI provider.
  • dbt-osmosis[azure] installs Azure AD authentication support for Azure OpenAI; use it together with dbt-osmosis[openai] for LLM_PROVIDER=azure-openai-ad.
  • dbt-osmosis[proxy] only installs dependencies for the experimental opt-in SQL proxy runtime; it does not imply production support, start a proxy server, configure authentication, TLS, or listen/bind settings, or make comment middleware durable. The proxy module entrypoint is a local-only experiment with mysql-mimic defaults, not a hardened user-facing server; do not expose it to untrusted networks. The proxy comment middleware is in-memory only, and ticket:c10proxy25 owns proxy support semantics.

Verify​

dbt-osmosis --help

Replace <adapter> with your dbt adapter (for example: snowflake, bigquery, postgres, redshift, duckdb).