dbt-protos is a Python library that provides public Protocol Buffer (proto) bindings for dbt. It serves as a central, 100% generated repository for dbt's public proto definitions, facilitating internal communication and metadata handling within the dbt ecosystem. Currently at version 1.0.443, its release cadence is closely tied to dbt Core and other related dbt libraries.
Install & Compatibility
Where this runs
tested against v1.0.514 · 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.
Project
✓ from dbtlabs.dbt_common_pb2 import Project
✗ from dbtlabs.dbt_common_pb2 import Project
This quickstart demonstrates how to import and instantiate a generated Protocol Buffer message from `dbt-protos`. Since `dbt-protos` is primarily a binding library for internal dbt structures, direct end-user application logic using these protos is less common than other dbt libraries. This example uses a hypothetical 'Project' message from `dbt_common_pb2`.
from dbt_protos.dbt_common_pb2 import Project
# Instantiate a generated proto message (e.g., a 'Project' message)
project_message = Project(name="my_dbt_project", dbt_version="1.8.0")
print(f"Created dbt Project message: {project_message.name} (dbt version: {project_message.dbt_version})")
Debug
Known issues
breakingIncompatible Protobuf Gencode/Runtime Versions: Using `dbt-protos` with an older `protobuf` runtime than the version it was generated with can lead to `google.protobuf.runtime_version.VersionError`. This is a common issue with any protobuf-generated code.fixEnsure your installed `protobuf` library version is compatible with, or newer than, the version used to generate `dbt-protos`. Check the `protobuf` dependency requirements of `dbt-protos` or related `dbt-core` versions.
affects: All versions where protobuf runtime/gencode mismatch occurs
gotchaLibrary is 100% Generated: `dbt-protos` is entirely generated code. Direct modifications to its files are not recommended as they will be overwritten by future updates. This also means the API surface is dictated by the underlying .proto definitions.fixDo not manually edit files within the `dbt_protos` package. If changes to dbt's protobuf definitions are needed, engage with the dbt Labs team through their official channels.
affects: All versions
gotchaPrimarily an Internal/Foundational Library: `dbt-protos` provides low-level bindings for dbt's internal communication and metadata. It is not typically used for direct end-user data transformation logic or application development in the same way `dbt-core` or adapter plugins are. Expectations of a rich, high-level API for general use may lead to confusion.fixUnderstand that `dbt-protos` is foundational. Most users will interact with dbt through `dbt-core`, dbt adapters, or other higher-level dbt libraries. Direct usage is typically reserved for advanced integrations or metadata inspection.
affects: All versions
breakingThe `dbt-protos` library was not found in the Python environment. This typically means it was not installed, or the current environment does not have access to it.fixEnsure `dbt-protos` is properly installed in your Python environment using `pip install dbt-protos`. If using a virtual environment, ensure it is activated.
affects: All versions
breakingModuleNotFoundError: No module named 'dbt_protos'. This error occurs when the `dbt-protos` package is not found in the Python environment's path.fixEnsure `dbt-protos` is correctly installed in your Python environment. This can typically be resolved by running `pip install dbt-protos`. If using a virtual environment, ensure it is activated before installation.
affects: All versions
Audit
Dependencies
protobufrequiredRuntime dependency for handling Protocol Buffer messages.