Install & Compatibility
Where this runs
tested against v0.13.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.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 152.7MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 13.8s · import 0.000s · 149MB
153MB installed
● package 153MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MetricFlow CLI commands
✓ Interaction is primarily via the dbt CLI using 'dbt sl <command>' or 'mf <command>'. Direct Python API imports for end-user semantic layer querying are not the primary interaction model.
dbt-metricflow is largely a CLI-driven tool, extending dbt Core with semantic layer capabilities. Users interact with it through dbt CLI commands like `dbt sl list metrics` rather than importing Python classes for high-level operations.
This quickstart demonstrates how to interact with dbt-metricflow functionality through the `dbt sl` CLI commands using Python's `subprocess` module. This is the primary way users query and validate semantic layer definitions. Ensure you have a dbt project with semantic models and metrics configured, and dbt-metricflow (with an appropriate adapter) installed in your environment.
import subprocess
import os
# This assumes a dbt project with semantic models and metrics defined is set up.
# And dbt-metricflow (with an adapter) is installed in the environment.
# Example: List available metrics in your dbt project
print("Listing dbt metrics...")
result = subprocess.run(['dbt', 'sl', 'list', 'metrics'], capture_output=True, text=True, check=False)
print(result.stdout)
if result.stderr:
print(f"Error: {result.stderr}")
# Example: Validate your semantic layer configurations
print("Running dbt semantic layer health checks...")
result = subprocess.run(['dbt', 'sl', 'health-check'], capture_output=True, text=True, check=False)
print(result.stdout)
if result.stderr:
print(f"Error: {result.stderr}")
dbt --version
Debug
Known issues
breakingThe `dbt-metricflow` package encapsulates `dbt-core`, `MetricFlow`, and `dbt-adapters` to manage version compatibility. Directly installing individual `dbt-core` or `MetricFlow` packages might lead to version conflicts due to dependencies on `dbt-semantic-interfaces`. Always prefer installing `dbt-metricflow[adapter]` to ensure a compatible bundle.fixUse `pip install "dbt-metricflow[adapter_package_name]"` to ensure bundled and compatible versions are installed. Refer to the PyPI page for supported adapters and their versions.
affects: <0.11.0
gotchaMetricFlow (the underlying library) does not currently support dbt built-in functions or packages within semantic models. This can limit the complexity of logic directly expressible in metric definitions.fixDesign your dbt models to pre-process data into a suitable format before defining semantic models and metrics, or structure your logic to avoid unsupported dbt functions within MetricFlow's scope. Check the official documentation for planned future support.
affects: All versions
deprecatedOlder versions of MetricFlow CLI users were required to install a separate `metricflow` package. As of MetricFlow 0.206.0, CLI updates are picked up by installing `dbt-metricflow`.fixEnsure you are installing `dbt-metricflow` to get the latest CLI features and updates. The `dbt sl` prefix for commands is generally recommended.
affects: MetricFlow <0.206.0
gotchaWhen integrating with tools like Hex, enabling the dbt semantic layer integration on the data connection can break prepared statements required for no-code filtering.fixAvoid enabling the dbt semantic layer integration on the data connection if you require prepared statements for no-code filtering in tools like Hex. Consider alternative methods for syncing or managing schema in such cases.
affects: All versions
Upgrade
Version history
0.13.0latest on PyPI · released May 12, 2026
Audit
Dependencies
pythonrequiredRequired Python version range.
dbt-corerequireddbt-metricflow bundles dbt-core to ensure compatibility for the semantic layer functionality. The specific dbt-core version is managed by the dbt-metricflow bundle.
dbt-adapteroptionalSpecific dbt adapters (e.g., dbt-snowflake, dbt-postgres) are required to connect to a data warehouse. These are installed as extras.
graphvizoptionalOptional for certain visualization features or advanced setups.
postgresqloptionalOptional for certain local setups or specific database connections.