Registry / workflow / prefect-dbt

prefect-dbt

JSON →
library0.7.25pypypi✓ verified 26d ago

Prefect-dbt is an official Prefect integration for orchestrating dbt (data build tool) projects within Prefect workflows. It provides tasks and blocks for interacting with the dbt CLI, allowing users to run dbt commands (like `dbt run`, `dbt test`, `dbt build`) as part of their data pipelines. The current version is 0.7.20, and it follows Prefect's release cadence for integrations, with updates typically coinciding with or following major Prefect releases.

pip install prefect-dbt
INSTALL
IMPORT
SIG · PREFECT-DBT
P
prefect-dbt
workflowpythonv0.7.25
Install
29.9s avg
Import
12138ms
Disk
335MB
Pass rate
6/ 10
Env Coverage6 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.7.25 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 34s
py 3.11
✕ build_error
✓ 32.5s
py 3.12
✕ build_error
✓ 26.3s
py 3.13
✕ build_error
✓ 26.1s
py 3.9
✓ —
✓ 30.7s
335MB installed
● package 335MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

DbtCloudCredentials
✓ from prefect_dbt import DbtCloudCredentials
✗ from prefect_dbt.cli import DbtCli
DbtCloudJob
✓ from prefect_dbt import DbtCloudJob
PrefectDbtRunner
✓ from prefect_dbt import PrefectDbtRunner

This quickstart demonstrates a simple Prefect flow that uses `prefect-dbt` to execute the `dbt debug` command. This is a good starting point as it verifies the dbt installation and profile configuration without requiring a full dbt project or database connection. For `dbt run`, `dbt test`, etc., you would typically set up a `DbtCliProfile` block in the Prefect UI and load it in your flow.

import os from prefect import flow, get_run_logger from prefect_dbt.cli import DbtCli @flow(log_prints=True) def dbt_cli_debug_flow(): """ A simple Prefect flow that runs `dbt debug` using the prefect-dbt integration. This demonstrates basic interaction with the dbt CLI via Prefect. """ logger = get_run_logger() # Initialize DbtCli. By default, it looks for dbt in the PATH # and profiles.yml in the standard dbt locations or specified via env vars. dbt_cli = DbtCli() logger.info("Attempting to run `dbt debug`...") # Run the `debug` command. This checks dbt installation and profiles. # It usually doesn't require a specific dbt project directory or database connection to run. try: debug_result = dbt_cli.debug() logger.info(f"dbt debug completed with return code: {debug_result.return_code}") logger.info(f"dbt debug stdout:\n{debug_result.stdout}") if debug_result.return_code != 0: logger.error(f"dbt debug stderr:\n{debug_result.stderr}") raise RuntimeError(f"`dbt debug` failed with return code {debug_result.return_code}") except Exception as e: logger.error(f"Failed to execute dbt debug: {e}") logger.warning( "Ensure 'dbt-core' is installed in your execution environment " f"(`pip install dbt-core` or specific adapter like `pip install dbt-postgres`)." ) raise if __name__ == "__main__": dbt_cli_debug_flow() # For local execution # To deploy: dbt_cli_debug_flow.to_deployment(name="dbt-debug-deployment").apply()
Debug
Known issues
deprecatedThe `dbt_cli_task` function has been deprecated in favor of the `DbtCli` class and its methods. The `DbtCli` class provides a more object-oriented interface and integrates better with Prefect Blocks for managing dbt profiles.
fix
Migrate from `from prefect_dbt.cli import dbt_cli_task` to `from prefect_dbt.cli import DbtCli` and instantiate the class to call dbt commands (e.g., `DbtCli().run()`).
affects: 0.6.0 onwards
gotchaThe `prefect-dbt` library acts as a wrapper for the dbt CLI. This means `dbt-core` (and any necessary dbt adapters like `dbt-postgres`, `dbt-bigquery`) must be installed separately in the environment where your Prefect flow runs. `prefect-dbt` does not automatically install `dbt-core`.
fix
Ensure `dbt-core` and your chosen dbt adapter are installed in your flow's execution environment using `pip install dbt-core [your-adapter]`.
affects: All versions
gotchaManaging dbt profiles and credentials: While `prefect-dbt` can work with `profiles.yml` files in the execution environment, the recommended Prefect pattern for secure and centralized credential management is to use `DbtCliProfile` Blocks.
fix
Create a `DbtCliProfile` block in the Prefect UI with your dbt profile configuration. Then, load and pass this block to `DbtCli` (e.g., `DbtCli(dbt_profile=DbtCliProfile.load('my-profile'))`).
affects: All versions
gotchaDbt CLI version compatibility: `prefect-dbt` is designed to work with various `dbt-core` versions, but significant changes in the dbt CLI's arguments or output can lead to unexpected behavior. Always verify compatibility with your specific `dbt-core` version.
fix
Consult the `prefect-dbt` documentation for supported `dbt-core` versions. Test your flows thoroughly after upgrading either `prefect-dbt` or `dbt-core`.
affects: All versions
Upgrade
Version history
0.7.25latest on PyPI · released Jun 5, 2026
Audit
Dependencies
prefectrequiredCore dependency for Prefect flows and tasks.
dbt-coreoptionalRequired in the execution environment to run dbt commands, but not a direct Python dependency of 'prefect-dbt' itself. Users must install dbt-core (or a specific adapter like dbt-postgres) separately.
Agent activity
29 hits · last 30 days
node
26
OpenAI (training)
1
Resources
homepagenull ↗
prefect-dbt — pip install prefect-dbt · libregistry