---
id: metricflow
version: "0.212.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# metricflow — Translates a simple metric definition into reusable SQL and executes it against the SQL engine of your choice.

License: permissive · Maintenance: active · Downloads: 4.3M/mo

## What it is and what it does

MetricFlow is a semantic layer that translates metric definitions into SQL queries optimized for your data warehouse. It abstracts away the complexity of multi-hop joins between fact and dimension tables, handles advanced metric types (ratio, expression, cumulative), and manages aggregation across different time granularities. The package compiles metric requests into a dataflow-based query plan, optimizes it, and renders engine-specific SQL.

MetricFlow is designed to work within the dbt ecosystem as a query compilation and SQL rendering library. It requires a working dbt project and dbt adapter to function. The package depends on 12 runtime libraries including jinja2, pydantic, sqlglot, and pyyaml to handle templating, validation, SQL parsing, and configuration. It supports Python 3.10 through 3.14 and is actively maintained.

Use it for:

- Define metrics once in code and automatically generate consistent SQL queries across multiple data warehouses.
- Build complex ratio metrics, cumulative metrics, and expressions that depend on multiple fact and dimension tables.
- Aggregate metrics to different time granularities without rewriting query logic.
- Maintain a centralized semantic layer for metrics used across analytics, BI tools, and reporting dashboards.
- Integrate metric definitions into version-controlled, testable metric logic within existing workflows.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

MetricFlow compiles metric definitions into reusable SQL queries, handling multi-hop joins, complex metric types, and aggregations across different time granularities.

Yes, if you need to centralize metric logic in code. MetricFlow is actively maintained, has no known vulnerabilities, carries a permissive Apache-2.0 license, and installs with low friction. It solves a real problem—metric consistency and reusability—but requires a dbt project and adapter to work, so it is not a standalone tool. Best suited for teams already invested in dbt.

## Install

pip install metricflow
uv add metricflow
poetry add metricflow

## Installing metricflow

Before you install: Low install friction with a pure Python wheel. Active maintenance with a release 2 days ago. Supports Python 3.10 through 3.14. Requires a working dbt project and dbt adapter to function; optional system dependencies include Postgres and Graphviz.

License in practice: Apache-2.0 permissive license. Version 0.212.0 is covered by Apache-2.0 (versions 0.209.0 and greater); earlier versions were under AGPL or BSL, so this version carries no copyleft obligations.

Quickstart:

pip install metricflow

import metricflow
# Requires a working dbt project and dbt adapter configured before use

Requires a working dbt project, a dbt adapter, and optionally Postgres or Graphviz installed on the system.

Verify before relying:

- Whether the package can be used standalone or strictly requires dbt project integration for all operations.
- Performance characteristics and scalability limits for large metric definitions or complex joins.
- Whether Postgres and Graphviz are required or only needed for specific features.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 4.3M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

metric definition to SQL compiler, semantic layer for metrics, metric query generation, SQL metric compilation, data warehouse metric abstraction, dimension-aware metric queries, metric aggregation engine, sql-generation, semantic-layer, metric-management

[View on SkillFed](https://skillfed.io/packages/metricflow) · [View on PyPI](https://pypi.org/project/metricflow/)