---
id: luqum
version: "1.0.0"
license: unclear
license_treatment: unclear
maintenance: active
---

# luqum — A Lucene query parser generating ElasticSearch queries and more !

License: unclear · Maintenance: active · Downloads: 2.4M/mo

## What it is and what it does

Luqum is a Lucene Query DSL parser that builds an abstract syntax tree from Lucene query strings, allowing you to inspect, analyze, and programmatically manipulate search queries. It depends only on PLY (Python Lex-Yacc) and runs on Python 3.10+. The primary use case is transforming user-written Lucene queries into Elasticsearch JSON DSL, while also supporting custom transformations and enrichments—for example, adding support for nested object searches or applying field-specific query logic.

The package has been actively developed since 2016, recently reaching version 1.0.0 (2025-02-18) with support for Python 3.11, 3.12, and 3.13. It handles a range of Lucene features including boolean operations, proximity and fuzzy matching, range queries, wildcards, and escape sequences. The dual Apache 2.0 / LGPLv3+ licensing provides flexibility for most projects, though the package metadata does not yet clearly expose which license applies.

Use it for:

- Transform user-facing Lucene query syntax into Elasticsearch JSON DSL for backend execution.
- Validate and analyze Lucene queries before sending them to a search engine.
- Enrich or rewrite Lucene queries programmatically (e.g., add field restrictions, rewrite operators).
- Build query visualization or debugging tools that explain why a query matches certain results.
- Support nested object searches or custom field treatments by intercepting and modifying the query tree.

## Worth the install?

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

Parses Lucene Query DSL syntax into an abstract syntax tree, enabling inspection, analysis, and transformation of search queries for use with Elasticsearch or custom backends.

Yes. Luqum is actively maintained, has low install friction, carries no known vulnerabilities, and solves a specific problem well: parsing and transforming Lucene queries. Install it if you need to accept Lucene syntax from users and convert it to Elasticsearch or apply custom query logic. Verify the dual license terms (Apache 2.0 / LGPLv3+) match your project's requirements before committing.

## Install

pip install luqum
uv add luqum
poetry add luqum

## Installing luqum

Before you install: Low install friction with a single lightweight dependency (ply >= 3.11). Actively maintained; last commit 2026-04-14 with recent version 1.0.0 released 2025-02-18. Supports Python 3.10+.

License in practice: Dual-licensed under Apache 2.0 and LGPLv3+, but license metadata is unclear in the package record. Verify the actual license terms before use in proprietary or GPL-incompatible projects.

Quickstart:

pip install luqum

from luqum.parser import parser

tree = parser.parse('author.last_name:Smith OR author:(age:[25 TO 34])')
print(tree)

Requires Python 3.10 or later; earlier versions no longer supported as of 0.14.0.

Verify before relying:

- Whether license metadata (SPDX/raw) will be clarified in future releases to resolve the 'unclear' treatment flag.
- Performance characteristics when parsing very large or deeply nested Lucene queries.
- Completeness of Elasticsearch DSL transformation support for all Lucene operators and edge cases.

## Package facts

- License: not declared (unclear)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 2.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

lucene query parser, lucene dsl to elasticsearch, query syntax tree builder, search query manipulation, lucene ast parser, elasticsearch query transformation, query-parsing, elasticsearch, lucene

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