---
id: promql-parser
version: "0.10.0"
license: unclear
license_treatment: unclear
maintenance: active
---

# promql-parser

License: unclear · Maintenance: active · Downloads: 430.5K/mo

## What it is and what it does

promql-parser is a Python binding to a Rust-based PromQL parser that converts Prometheus query expressions into an inspectable AST. It lets you parse queries like `rate(http_requests_total{job="api"}[5m])` into structured objects (VectorSelector, MatrixSelector, Call, AggregateExpr, BinaryExpr) that you can examine, walk depth-first, or transform into new expressions. The package also includes duration helpers to parse and format time intervals.

Typical workflows involve parsing a PromQL string, inspecting its structure to extract metric names or matchers, walking the tree to collect information, or transforming nodes to rewrite queries. The AST can be converted back to PromQL string form. No runtime dependencies are required beyond Python itself.

Use it for:

- Extract metric names and label matchers from Prometheus queries for validation or analysis.
- Rewrite or transform PromQL expressions programmatically (e.g., rename metrics, adjust time ranges).
- Build tooling that inspects or validates Prometheus query syntax before execution.
- Walk query trees to collect metadata or enforce query patterns in monitoring systems.
- Parse duration strings from PromQL into Python timedelta objects.

## Worth the install?

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

Parses Prometheus query language (PromQL) expressions into a Python-accessible abstract syntax tree that can be inspected, walked, transformed, and formatted back to PromQL.

Yes, if you need to parse or manipulate PromQL queries in Python. The package is actively maintained, has no known vulnerabilities, supports Python >=3.8, and requires no runtime dependencies. Medium install friction (prebuilt wheels for common platforms) is a minor trade-off for a specialized tool with a clear use case.

## Install

pip install promql-parser
uv add promql-parser
poetry add promql-parser

## Installing promql-parser

Before you install: Medium install friction due to compiled wheels; prebuilt binaries available for Python 3.10–3.11 on common platforms. Active maintenance with latest release 67 days ago.

Quickstart:

pip install promql-parser

import promql_parser

ast = promql_parser.parse('prometheus_http_requests_total{code="200", job="prometheus"}')
print(ast.prettify())

Requires Python >=3.8; prebuilt wheels available for Python 3.10–3.11 on Linux, macOS, and Windows.

Verify before relying:

- Whether the Rust implementation is vendored or requires a separate build toolchain for platforms without prebuilt wheels.
- Whether PyPy support (listed in classifiers) is fully tested or aspirational.
- License details: license_spdx and license_raw are both null despite MIT being mentioned in the description.

## Package facts

- License: not declared (unclear)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 430.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

promql parser, prometheus query parsing, promql ast, parse prometheus expressions, promql syntax tree, prometheus query language parser, promql expression analysis, prometheus, query-parsing, rust-bindings

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