dbt-core
raw JSON → 1.11.7 verified Tue May 12 auth: no python install: verified quickstart: verified
dbt-core is the open-source foundation of dbt (data build tool), empowering data analysts and engineers to transform data in their warehouses using SQL, following software engineering best practices. It's a powerful CLI tool for building, testing, documenting, and deploying data models. `dbt-core` is currently at version 1.11.7 and adheres to semantic versioning, with minor versions being backward compatible and frequent patch releases for bug fixes.
pip install dbt-core Common errors
error Compilation Error ↓
cause 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.
fix
Carefully 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. error Runtime Error Could not find profile named '...' ↓
cause 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.
fix
Ensure 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. error ModuleNotFoundError: No module named 'dbt.adapters.factory' ↓
cause 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.
fix
Reinstall
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. error fatal: Not a git repository (or any of the parent directories): .git ↓
cause 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.
fix
Navigate 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. error Database Error: SQL compilation error: syntax error ↓
cause 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.
fix
Review 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. Warnings
breaking Explicit 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. ↓
fix Always explicitly install both `dbt-core` and your desired adapter: `pip install dbt-core dbt-<adapter_name>`.
gotcha Programmatic `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. ↓
fix To 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.
deprecated Setting custom global config flags in `profiles.yml` has been deprecated. These flags should now be configured in `dbt_project.yml`. ↓
fix Move global config flags from `profiles.yml` to the `flags` dictionary in `dbt_project.yml`.
breaking Major 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. ↓
fix Always consult the official dbt Developer Hub migration guides and changelogs before upgrading to a new major version.
deprecated Beginning 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. ↓
fix Review 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.
gotcha dbt 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). ↓
fix Be 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.
gotcha A 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. ↓
fix Review 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.
Install
pip install dbt-core dbt-<adapter_name> Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) - - 7.99s 113.7M
3.10 alpine (musl) - - - -
3.10 slim (glibc) - - 4.89s 114M
3.10 slim (glibc) - - - -
3.11 alpine (musl) - - 9.81s 125.6M
3.11 alpine (musl) - - - -
3.11 slim (glibc) - - 6.92s 126M
3.11 slim (glibc) - - - -
3.12 alpine (musl) - - 9.28s 115.3M
3.12 alpine (musl) - - - -
3.12 slim (glibc) - - 8.08s 116M
3.12 slim (glibc) - - - -
3.13 alpine (musl) - - 7.94s 114.9M
3.13 alpine (musl) - - - -
3.13 slim (glibc) - - 6.70s 115M
3.13 slim (glibc) - - - -
3.9 alpine (musl) - - 7.87s 112.1M
3.9 alpine (musl) - - - -
3.9 slim (glibc) - - 6.42s 112M
3.9 slim (glibc) - - - -
Imports
- dbtRunner
from dbt.cli.main import dbtRunner - dbtRunnerResult
from dbt.cli.main import dbtRunnerResult
Quickstart verified last tested: 2026-04-23
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}")