---
id: hogql-parser
version: "1.3.83"
license: MIT
license_treatment: permissive
maintenance: active
---

# hogql-parser — HogQL parser for internal PostHog use

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

## What it is and what it does

HogQL Parser is a native C++ extension for Python that parses HogQL query expressions, SELECT statements, and Hog programs into abstract syntax trees. It wraps an ANTLR4-based parser shared with a WebAssembly version for JavaScript. The package is designed for internal PostHog use and supports Python 3.10 through 3.13 on macOS and Linux platforms.

The parser accepts HogQL syntax—a SQL-like query language—and produces structured ASTs that can be consumed by downstream tools. It has no runtime dependencies and installs via prebuilt wheels for supported architectures, though Windows is not supported. The package is actively maintained and has seen recent releases.

Use it for:

- Parse HogQL expressions in PostHog analytics pipelines to validate or transform user queries
- Build development tools or IDE plugins that need to understand HogQL syntax and structure
- Integrate HogQL query parsing into backend services running on Linux or macOS infrastructure
- Generate ASTs for query optimization or analysis in analytics platforms

## Worth the install?

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

Parses HogQL query expressions and Hog programs into abstract syntax trees, available as a native C++ extension for Python on macOS and Linux.

Yes, if you are building on PostHog or need to parse HogQL syntax on macOS or Linux. The package is actively maintained, has no known vulnerabilities, uses a permissive MIT license, and ranks in the top 5000 PyPI packages by downloads. Install friction is moderate due to platform and architecture constraints—Windows users cannot use it. Verify that the Python API matches your needs before committing.

## Install

pip install hogql-parser
uv add hogql-parser
poetry add hogql-parser

## Installing hogql-parser

Before you install: Medium install friction due to platform-specific prebuilt wheels; requires macOS or Linux with x86_64 or arm64 architecture. Active maintenance with recent releases and no known vulnerabilities.

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

pip install hogql_parser

from hogql_parser import parse_expr

ast = parse_expr('1 + 2')
print(ast)

Requires macOS or Linux; Windows is not supported. Python 3.10 or later required.

Verify before relying:

- Exact API surface and return types for Python parse functions (description shows npm API but Python equivalents not detailed)
- Whether parse functions return JSON strings or native Python objects in the Python package
- Error handling behavior in Python (whether errors are raised or returned as objects like the npm version)

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 2.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

hogql parser python, query expression parser, ast generation from sql, hog language parser, posthog query parsing, antlr4 based parser, sql-like query parser, query-parsing, posthog-ecosystem, antlr4

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