Install & Compatibility
Where this runs
tested against v1.12.3 · 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
py 3.10
✕ build_error
1/2 runs
py 3.11
✕ build_error
1/2 runs
py 3.12
✕ build_error
1/2 runs
py 3.13
✕ build_error
1/2 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
dbtRunner
✓ from dbt.cli.main import dbtRunner
This is the primary programmatic entry point for invoking dbt CLI commands within Python. Available since dbt Core v1.5.
dbtRunnerResult
✓ from dbt.cli.main import dbtRunnerResult
Used to inspect the results of a dbtRunner invocation.
This quickstart demonstrates how to programmatically invoke dbt CLI commands using the `dbtRunner` class. It shows how to run all models in an existing dbt project and process the results. A `dbt_project.yml` and `profiles.yml` must be set up for this to execute successfully. The `dbtRunner` class was introduced in dbt Core v1.5 as the official Python entry point.
import os
from dbt.cli.main import dbtRunner, dbtRunnerResult
# NOTE: For this to run, you must have a dbt project initialized
# (e.g., with 'dbt init <project_name>') and a profiles.yml configured.
# Set the DBT_PROFILES_DIR environment variable or ensure 'dbt_project.yml'
# is in the current working directory or a parent directory.
# A simple dbt_project.yml might look like:
# name: my_dbt_project
# version: '1.0.0'
# config-version: 2
# profile: my_profile
# Initialize the dbt runner
dbt = dbtRunner()
# Example: Run all models in your dbt project
# You might need to set the project directory explicitly if not in CWD
project_directory = os.environ.get('DBT_PROJECT_DIR', os.getcwd())
cli_args = ["run", "--project-dir", project_directory]
print(f"Invoking dbt run with arguments: {cli_args}")
res: dbtRunnerResult = dbt.invoke(cli_args)
if res.success:
print("dbt run completed successfully.")
if res.result:
for r in res.result:
print(f" Model: {r.node.name}, Status: {r.status}")
else:
print("dbt run failed.")
if res.exception:
print(f"Exception: {res.exception}")
elif res.result:
# Some commands might return partial results even on failure
print("Partial results or errors:")
for r in res.result:
print(f" Model: {r.node.name}, Status: {r.status}, Message: {r.message}")
dbt --version
Debug
Known issues
breakingExplicit installation of both `dbt-core` and adapter plugins is now recommended. Prior to v1.8, installing an adapter (e.g., `dbt-snowflake`) implicitly installed `dbt-core`. While this implicit behavior is maintained for backward compatibility currently, it may be removed in future versions.fixAlways explicitly install both `dbt-core` and your desired adapter: `pip install dbt-core dbt-<adapter_name>`.
affects: >=1.8
gotchaProgrammatic `dbtRunner` invocations in the same Python process do not support safe parallel execution. Running multiple dbt commands concurrently within a single process is discouraged due to potential interactions with global Python variables and data platform conflicts.fixTo achieve parallel execution safely, run dbt commands in separate processes (e.g., using `subprocess`, `Celery`) or utilize tools like the dbt CLI or dbt Cloud IDE which manage concurrency.
affects: >=1.5
deprecatedSetting custom global config flags in `profiles.yml` has been deprecated. These flags should now be configured in `dbt_project.yml`.fixMove global config flags from `profiles.yml` to the `flags` dictionary in `dbt_project.yml`.
affects: >=1.8
breakingMajor versions (e.g., v1 to v2) of dbt Core may introduce breaking changes, including the removal of deprecated functionality. Minor versions (e.g., v1.8 to v1.9) are generally backward compatible for documented features.fixAlways consult the official dbt Developer Hub migration guides and changelogs before upgrading to a new major version.
affects: All major version upgrades
deprecatedBeginning in v1.10, dbt Core will issue deprecation warnings for invalid dbt code, including custom inputs, duplicate YAML keys, and unexpected Jinja blocks, which will become invalid in future versions.fixReview and address deprecation warnings promptly. Ensure `dbt_project.yml` and YAML property files adhere to recommended structures and avoid standalone anchor definitions at the top level.
affects: >=1.10
gotchadbt Python models (`.py` files) are executed remotely on the configured data platform (e.g., Snowflake, BigQuery, Databricks), not on the local machine where `dbt-core` is running. This means any Python code must be compatible with the platform's execution environment and its limitations (e.g., external API calls might not be supported).fixBe aware of your data platform's Python runtime capabilities and limitations when developing dbt Python models. Do not assume local Python environment features are available remotely.
affects: >=1.3 (when Python models were introduced)
gotchaA shell error `sh: 1: cannot open <name>: No such file` indicates that a command executed after `dbt-core` installation tried to reference a non-existent file or command. This often happens when placeholders (e.g., `<adapter_name>`) are not replaced with actual values, or when a script expects a file that is not present.fixReview the script or command executed immediately after `pip install`. Ensure all placeholders like `<adapter_name>` are correctly substituted, and all referenced files or commands exist in the execution environment. This error is external to dbt-core itself.
affects: All versions
Errors
Common errors & fixes
Compilation Error
This error occurs when dbt cannot parse the code in your .sql or .yml files due to syntax issues in Jinja or SQL, or incorrect YAML formatting.
fixCarefully check the specified file for missing commas, incorrect spelling, capitalization issues, unclosed Jinja blocks (e.g., {% endmacro %}), or invalid ref/source functions. Use `dbt compile` to isolate and debug issues before running. Runtime Error Could not find profile named '...'
dbt cannot locate the specified profile in your profiles.yml file, or the profile: key in dbt_project.yml does not match an existing profile, or there are issues with credentials/authentication.
fixEnsure a `profiles.yml` file exists in `~/.dbt/` (or the directory specified by `DBT_PROFILES_DIR`), verify the profile name in `dbt_project.yml` exactly matches a profile in `profiles.yml`, and confirm credentials are correct. Run `dbt debug --config-dir` to locate your `profiles.yml` and `dbt debug` to test the connection.
ModuleNotFoundError: No module named 'dbt.adapters.factory'
This typically occurs after upgrading dbt-core to version 1.8 or higher, where dbt-core and its adapters were decoupled, leading to missing or incorrectly installed adapter dependencies.
fixReinstall `dbt-adapters` and your specific adapter (e.g., `dbt-bigquery`) forcefully using `pip install --force-reinstall dbt-adapters dbt-<your_adapter>`. It's recommended to explicitly install both `dbt-core` and the desired adapter, and consider reinstalling in a fresh virtual environment if issues persist.
fatal: Not a git repository (or any of the parent directories): .git
This error indicates that a Git command was attempted in a directory that is not part of a Git repository, or the .git folder is missing or corrupted.
fixNavigate to the root directory of your dbt project where the `.git` folder is located. If the project is not a Git repository, initialize it with `git init` or clone an existing repository. If the `.git` folder is corrupted, you might need to reinitialize or restore it.
Database Error: SQL compilation error: syntax error
dbt successfully compiles the Jinja and dbt-specific syntax, but the resulting SQL code contains a syntax error that the target data warehouse cannot execute. This often happens due to typos, incorrect functions for the specific database, or incompatible data types.
fixReview the SQL in the problematic model. Check the `target/compiled` directory to see the fully compiled SQL that dbt sends to the warehouse. Run this compiled SQL directly in your data warehouse's query editor to pinpoint the exact syntax issue using the warehouse's error messages.
Upgrade
Version history
1.12.3latest on PyPI · released Aug 21, 2026
Audit
Dependencies
pythonrequiredRequired to run dbt-core. PyPI metadata lists >=3.10.
dbt-adaptersrequiredProvides the base classes and utilities for dbt adapters.
dbt-commonrequiredProvides common utilities and shared code across dbt packages.
dbt-<adapter_name>optionalAn adapter for a specific data warehouse (e.g., dbt-snowflake, dbt-bigquery). Essential for dbt to connect to a database. Must be installed separately.