dbt-protos

1.0.443 verified Tue May 12 auth: no python install: stale quickstart: stale

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.

pip install dbt-protos

Common errors

error ModuleNotFoundError: No module named 'dbt_protos' ↓

cause The dbt-protos library is not installed in the active Python environment.

fix

pip install dbt-protos

error ModuleNotFoundError: No module named 'google' (often seen in tracebacks from 'dbt.events.types_pb2' or similar files) ↓

cause The 'protobuf' library, a core dependency for dbt-protos which provides Protocol Buffer bindings, is missing from the Python environment.

fix

pip install protobuf

error google.protobuf.runtime_version.VersionError: Detected incompatible Protobuf Gencode/Runtime versions ↓

cause The protobuf runtime library installed in your environment is an older version than the protobuf compiler (protoc) version used to generate the Python files within dbt-protos or related dbt libraries.

fix

Upgrade the protobuf library in your environment: 'pip install --upgrade protobuf'. If a specific version is required by other dbt components, you might need to constrain it, e.g., 'pip install "protobuf>=5.28.3,<6.0"'.

error ERROR: Could not find a version that matches protobuf<X.Y.Z,>=A.B.C (often seen when installing dbt-core, dbt-adapters, etc.) ↓

cause This 'dependency hell' occurs when multiple dbt ecosystem libraries (like dbt-core, dbt-adapters, dbt-semantic-interfaces, and implicitly dbt-protos) have conflicting and incompatible version requirements for the underlying protobuf library.

fix

Review all dbt-related packages and their protobuf requirements to find a compatible set. Try upgrading all dbt packages simultaneously (e.g., 'pip install dbt-core dbt-adapters dbt-protos --upgrade') or reinstalling them in a clean virtual environment to allow the package manager to resolve dependencies holistically.

Warnings

breaking Incompatible 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. ↓

fix Ensure 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.

gotcha Library 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. ↓

fix Do 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.

gotcha Primarily 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. ↓

fix Understand 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.

breaking The `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. ↓

fix Ensure `dbt-protos` is properly installed in your Python environment using `pip install dbt-protos`. If using a virtual environment, ensure it is activated.

breaking ModuleNotFoundError: No module named 'dbt_protos'. This error occurs when the `dbt-protos` package is not found in the Python environment's path. ↓

fix Ensure `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.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - - 21.5M

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 2.0s - 22M

3.10 slim (glibc) - - - -

3.11 alpine (musl) wheel - - 23.8M

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 1.9s - 25M

3.11 slim (glibc) - - - -

3.12 alpine (musl) wheel - - 15.6M

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 1.8s - 17M

3.12 slim (glibc) - - - -

3.13 alpine (musl) wheel - - 15.4M

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 1.8s - 16M

3.13 slim (glibc) - - - -

3.9 alpine (musl) wheel - - 20.9M

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 2.3s - 22M

3.9 slim (glibc) - - - -

Imports

Project
```
from dbt_protos.dbt_common_pb2 import Project
```
Example import for a common dbt object (e.g., Project from dbt_common). Specific imports will vary based on the desired proto message. This pattern is typical for generated protobuf Python bindings.

Quickstart stale last tested: 2026-04-24

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})")