Install & Compatibility
Where this runs
tested against v1.24.5 · 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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BaseAdapter
✓ from dbt.adapters.base.impl import BaseAdapter
For developers extending the base adapter functionality. End-users typically do not directly import from dbt-adapters Python modules.
SQLAdapter
✓ from dbt.adapters.sql.impl import SQLAdapter
For developers building SQL-based adapters, inheriting from BaseAdapter. End-users typically do not directly import from dbt-adapters Python modules.
adapter (Jinja context variable)
✓ {% do adapter.dispatch('macro_name', 'package_name')(arg1, arg2) %}
The primary way dbt users interact with adapter functionality within dbt models (via Jinja macros).
dbt-adapters is a low-level library for building dbt adapters. End-users interact with adapter functionality through dbt-core and specific database adapters. The quickstart below illustrates how a dbt user sets up a project and uses adapter-specific logic via Jinja macros in a SQL model, which leverages the interfaces provided by `dbt-adapters`.
# 1. Install dbt-core and your specific database adapter (e.g., dbt-postgres)
# pip install dbt-core dbt-postgres
# 2. Initialize a dbt project
# dbt init my_dbt_project
# cd my_dbt_project
# 3. Configure your profiles.yml (typically in ~/.dbt/profiles.yml)
# Example profiles.yml content (replace with your database details):
# my_dbt_project:
# target: dev
# outputs:
# dev:
# type: postgres
# host: localhost
# user: myuser
# password: "{{ env_var('DB_PASSWORD') }}"
# port: 5432
# dbname: mydatabase
# schema: public
# 4. Create a dbt model (e.g., models/my_model.sql)
# Use the 'adapter' object in Jinja to call adapter-specific functionality.
# For instance, to get the current timestamp, which might vary by database dialect:
-- my_model.sql
SELECT
{{ adapter.dispatch('current_timestamp', 'dbt')() }} as current_time,
1 as id
Debug
Known issues
breakingBreaking changes in dbt-core v1.8+ for adapter developers. dbt-core and dbt-adapters were decoupled. Adapters should no longer directly import from `dbt-core` and instead rely on interfaces defined in `dbt-adapters` and `dbt-common`. Users must explicitly install `dbt-core` and their specific `dbt-<adapter>` package.fixAdapter maintainers: Refactor imports to use `dbt-adapters` and `dbt-common` interfaces. Users: Always explicitly install `dbt-core` and your desired `dbt-<adapter>` (e.g., `pip install dbt-core dbt-snowflake`).
affects: dbt-core >= 1.8.0, dbt-adapters >= 1.0.0
gotchaAdapter methods like `get_response` and `execute` are expected to return `connection.AdapterResponse` objects, not just strings, since `dbt-core` v1.1. Custom adapters that return strings might face unexpected behavior.fixAdapter maintainers should update method implementations to return `dbt.contracts.connection.AdapterResponse` objects or a subclass thereof.
affects: dbt-core >= 1.1.0
gotchaCorrect configuration of `profiles.yml` is essential. Missing or incorrect entries, or failing to install the corresponding `dbt-<database-adapter>` package, will prevent dbt from connecting to your data warehouse and result in errors like 'Error importing adapter: No module named...'fixEnsure `profiles.yml` is correctly configured with `type` matching your installed adapter (e.g., `type: postgres` for `dbt-postgres`). Verify the specific `dbt-<database-adapter>` package is installed.
affects: All versions
deprecatedStarting with `dbt-core` v1.10, deprecation warnings are raised for custom inputs, duplicate YAML keys, and unexpected Jinja blocks. While initially warnings, these will become errors in future versions.fixReview and update dbt project configurations and custom macros to eliminate deprecated patterns. Consult dbt-core release notes for specific guidance on addressing warnings.
affects: dbt-core >= 1.10.0
breakingChanges to dbt artifact schema versions (e.g., manifest.json) require compatible `dbt-core` versions when using state-based functionality (`--state` flag). Mismatched schema versions will cause errors and require concurrent upgrades of dbt orchestrations.fixWhen upgrading, ensure all dbt environments and state-dependent jobs are updated to compatible `dbt-core` versions simultaneously.
affects: dbt-core >= 1.1.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'dbt.adapters.factory'
This error often occurs after upgrading dbt-core to version 1.8 or later without explicitly upgrading or reinstalling `dbt-adapters` or the specific database adapter, due to the decoupling of dbt-core and adapter packages.
fixReinstall or upgrade `dbt-adapters` and your specific dbt adapter (e.g., `dbt-bigquery`) alongside `dbt-core`. A common fix is `pip install --force-reinstall dbt-adapters dbt-<your-adapter-name>` or creating a fresh virtual environment and reinstalling everything.
ModuleNotFoundError: No module named 'dbt.adapters.base.impl'
This typically indicates an incompatibility between the installed `dbt-adapters` version and other dbt packages (like `dbt-core` or specific database adapters) after an upgrade or during dependency resolution.
fixEnsure all dbt-related packages (dbt-core, dbt-adapters, and your specific adapter) are compatible and updated together. Downgrading or forcing a reinstall of `dbt-adapters` to a compatible version often resolves the issue: `pip install dbt-adapters==<compatible-version>` or `pip install --upgrade dbt-core dbt-adapters dbt-<your-adapter-name>`.
Could not find adapter type <adapter_name>!
This error occurs when dbt-core cannot locate the installed adapter plugin for the specified database type in your `profiles.yml` file, often due to a missing adapter installation or an incompatible version.
fixInstall the correct dbt adapter package for your database (e.g., `pip install dbt-snowflake` for Snowflake) and ensure it's compatible with your `dbt-core` version. Verify that your `profiles.yml` correctly specifies the adapter type.
Command '['tar', '-zcf', '/tmp/dbt-workspace.tar.gz', 'xxx']' returned non-zero exit status 2.
This error often indicates that dbt commands are not being issued from the correct directory containing the `yarn.env` file, especially in environments like Cloudera Data Engineering (CDE).
fixEnsure you are running the dbt command from the directory immediately outside your dbt project (e.g., `~/my-project-dir/` if your project is `~/my-project-dir/sample-dbt-project`). Also, check the `DBT_PROJECT_NAME` variable in your `yarn.env` file.
Upgrade
Version history
1.24.5latest on PyPI · released Jul 15, 2026
Audit
Dependencies
dbt-commonrequiredProvides shared code utilized by both dbt-adapters and dbt-core for consistent functionality.
dbt-corerequireddbt-adapters defines the interface for dbt-core to interact with databases. While decoupled, a dbt environment requires both dbt-core and a specific adapter which builds on dbt-adapters.