Install & Compatibility
Where this runs
tested against v1.39.0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 71.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.5s · import 0.000s · 72MB
71MB installed
● package 71MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
__version__
✓ import dbt_common; print(dbt_common.__version__)
✗ import dbt_common; print(dbt_common.__version__)
This quickstart demonstrates how to import the `dbt_common` library and access its version. It also shows how to import and catch a base exception class, `DbtCommonError`, which is part of its utilities, illustrating basic programmatic interaction. Note that `dbt-common` is primarily an internal utility for `dbt-core` and adapters, so direct end-user application development with it is rare.
import dbt_common
from dbt_common.exceptions import DbtCommonError
print(f"dbt-common version: {dbt_common.__version__}")
try:
raise DbtCommonError("This is a dbt common error.")
except DbtCommonError as e:
print(f"Caught expected error: {e}")
Debug
Known issues
breakingMajor versions of `dbt-core` (e.g., v1 to v2) may include breaking changes that impact `dbt-common` and its consumers, particularly adapter plugins and custom implementations that rely on dbt's internal Python interfaces. These changes are typically communicated in dbt's release notes for adapter maintainers.fixRefer to the `dbt-core` release notes and migration guides for adapter developers. Update your adapter implementations to align with the new Python interfaces exposed or used by `dbt-common`.
affects: All major version upgrades of `dbt-core` (e.g., 1.x.x to 2.x.x)
breakingChanges to dbt's metadata interfaces, including artifacts (like `manifest.json`, `catalog.json`) and structured logging, are considered breaking for `dbt-common`'s consumers if fields are deleted, renamed, or their types/defaults change without backward compatibility.fixEnsure your tools or integrations parsing dbt artifacts are updated to handle the new schema versions. Monitor dbt Developer Hub for detailed artifact schema changes.
affects: Any minor or major version where metadata interface versions are bumped (e.g., dbt Core v1.x.x to v1.y.x or v2.x.x).
deprecatedThe `DBT_` environment variable prefix has been deprecated for custom variables to prevent collisions with dbt's internal variables. New dbt environment variables are now prefixed with `DBT_ENGINE`.fixUpdate any custom environment variables currently using the `DBT_` prefix to a different, non-colliding prefix, or ensure they do not conflict with dbt's internal `DBT_ENGINE` variables.
affects: dbt Core v1.10 onwards, impacting users with custom `DBT_` prefixed environment variables.
gotcha`dbt-common` is a foundational library, not typically intended for direct end-user application development. Its utilities are primarily consumed by `dbt-core` and dbt adapter implementations. Expect minimal direct documentation for independent usage.fixWhen using dbt, interact primarily with `dbt-core` or specific adapters. If you are developing a dbt adapter or extending `dbt-core`, refer to the `dbt-common` source code and dbt Labs' developer guides for internal API usage.
affects: All versions
Upgrade
Version history
1.39.0latest on PyPI · released Aug 11, 2026
Audit
Dependencies
pathspecrequiredUsed for file path matching and handling.
mashumarorequiredLikely for object serialization/deserialization.
coloramarequiredFor cross-platform colored terminal output.
isodaterequiredFor ISO 8601 date/time parsing and formatting.
dbt-protosrequiredFor Protocol Buffers definitions used in dbt communication and artifacts.
deepdiffrequiredFor deep comparison of data structures.
jinja2requiredCore templating engine used throughout dbt, including for SQL generation.
python-dateutilrequiredFor robust date/time parsing and manipulation.
agaterequiredA lightweight table-oriented data analysis library, potentially for internal data handling.
typing-extensionsrequiredFor backporting features from newer `typing` modules to older Python versions.
jsonschemarequiredFor validating JSON data against schemas, crucial for dbt artifacts.
protobufrequiredGoogle's Protocol Buffers for data serialization.
requestsrequiredFor making HTTP requests, common in various utility functions.