dbt-extractor

0.6.0 verified Tue May 12 auth: no python install: stale

dbt-extractor is a Python library that processes Jinja templates within dbt model files to analyze and extract metadata such as `ref`, `source`, and `config` calls. It is part of the `dbt-labs/dbt-parser-generator` repository. The tool, currently at version 0.6.0, prioritizes 100% certainty in its extraction, raising an exception if it cannot confidently extract values, rather than risking incorrect or incomplete output.

pip install dbt-extractor

Common errors

error Cargo, the Rust package manager, is not installed or is not on PATH ↓

cause dbt-extractor has Rust dependencies that require the Cargo package manager to be installed and accessible in the system's PATH during its installation process.

fix

Install Rust and Cargo by following the instructions on rustup.rs, then restart your shell and retry pip install dbt-core (or the specific dbt package that includes dbt-extractor).

error ImportError: DLL load failed while importing dbt_extractor: The specified procedure could not be found. ↓

cause This error often occurs on Windows when dbt-extractor, a dependency of dbt-core, cannot find a required dynamic-link library (DLL), possibly due to issues with Python virtual environments or missing Visual C++ Redistributables.

fix

Ensure your Python environment is correctly set up, consider reinstalling dbt-core and its dependencies in a fresh virtual environment, and verify that the necessary Microsoft Visual C++ Redistributables are installed for your Python version.

error [Bug] py_extract_from_source syntax errors for a seemingly correct dbt model sql ↓

cause dbt-extractor's strategy is to be 100% certain when extracting values from Jinja templates; if it encounters complex or ambiguous Jinja that it cannot confidently parse, it will raise an exception rather than risk incorrect extraction.

fix

Simplify the Jinja logic within the dbt model, or use a workaround if the Jinja structure is beyond what dbt-extractor can currently confidently resolve. This might involve restructuring macros or variables.

error ModuleNotFoundError: No module named 'dbt.adapters.factory' ↓

cause This error typically indicates an incompatibility or corruption in the installation of dbt-core and its adapter packages, often seen after upgrades or when different versions of dbt components are mixed.

fix

Perform a clean reinstallation of dbt-core and its specific adapter (e.g., dbt-snowflake, dbt-bigquery) by first uninstalling all dbt-related packages and then reinstalling them in a fresh virtual environment.

Warnings

gotcha Installation of `dbt-extractor` requires a Rust toolchain (specifically `cargo`) to compile its underlying components. Users without Rust installed will encounter build errors during `pip install`. ↓

fix Install Rust and Cargo via `rustup.rs` or your system's package manager before installing `dbt-extractor`.

gotcha The library's core strategy is to be 100% certain about its extractions. If it encounters Jinja it cannot confidently parse and extract, it will raise an `ExtractionError` instead of returning potentially incomplete or incorrect results. This means some valid dbt Jinja might not be processed by `dbt-extractor` and may require alternative rendering. ↓

fix Be prepared to handle `ExtractionError` and consider fallback mechanisms (e.g., dbt's native Jinja rendering) for complex or unsupported Jinja patterns.

gotcha `dbt-extractor` focuses on Jinja syntax extraction and does not perform validation of the underlying SQL syntax, schema existence, or data types. Errors in these areas will not be caught by `dbt-extractor` during compilation and will only manifest at runtime when dbt executes the SQL against your data warehouse. ↓

fix Supplement `dbt-extractor` usage with other tools like SQL linters (e.g., SQLFluff) and comprehensive dbt tests to ensure SQL correctness and data integrity.

bug There is an open bug where installation fails on free-threaded Python 3.14t, reporting an `ImportError: DLL load failed while importing dbt_extractor`. ↓

fix Avoid using free-threaded Python 3.14t or newer versions until this issue is resolved. Stick to officially supported Python versions (currently `>=3.9`).

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - - 19.2M

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 1.5s - 19M

3.10 slim (glibc) - - - -

3.11 alpine (musl) wheel - - 21.1M

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 1.6s - 21M

3.11 slim (glibc) - - - -

3.12 alpine (musl) wheel - - 12.9M

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 1.5s - 13M

3.12 slim (glibc) - - - -

3.13 alpine (musl) wheel - - 12.7M

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 1.4s - 13M

3.13 slim (glibc) - - - -

3.9 alpine (musl) wheel - - 18.7M

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 1.8s - 19M

3.9 slim (glibc) - - - -

Imports

extract_from_source

from dbt_extractor.main import extract_from_source

ExtractionError

from dbt_extractor.extractor import ExtractionError

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to use `dbt-extractor` to parse a dbt model's SQL content and extract references to other models (`ref`), sources (`source`), and configurations (`config`). If the extraction is not 100% certain, an `ExtractionError` will be raised.

from dbt_extractor.main import extract_from_source
from dbt_extractor.extractor import ExtractionError

dbt_model_content = """
SELECT
    {{ ref('my_model') }} as model_data,
    {{ source('my_schema', 'my_table') }} as source_data,
    {{ config(materialized='table') }}
FROM some_table
"""

try:
    extracted_data = extract_from_source(dbt_model_content)
    print("Extracted Refs:", extracted_data.refs)
    print("Extracted Sources:", extracted_data.sources)
    print("Extracted Configs:", extracted_data.configs)
except ExtractionError as e:
    print(f"Extraction failed: {e}")