Install & Compatibility
Where this runs
tested against v2.1.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.910 runs
installs and imports cleanly · install 0.0s · import 0.096s · 20.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.2s · import 0.089s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
jsonquery
✓ from jsonquerylang import jsonquery
✗ from jsonquery import jsonquery
The official module name changed from 'jsonquery' to 'jsonquerylang' to avoid conflict with an older, unrelated library. Always use 'jsonquerylang'.
parse
✓ from jsonquerylang import parse
compile
✓ from jsonquerylang import compile
stringify
✓ from jsonquerylang import stringify
This quickstart demonstrates how to use `jsonquery` with both text-based and JSON-formatted queries. It also shows basic usage of `parse` and `stringify` to convert between query formats.
from jsonquerylang import jsonquery
from pprint import pprint
data = {
"friends": [
{"name": "Chris", "age": 23, "city": "New York"},
{"name": "Emily", "age": 19, "city": "Atlanta"},
{"name": "Joe", "age": 32, "city": "New York"},
{"name": "Kevin", "age": 19, "city": "Atlanta"},
{"name": "Michelle", "age": 27, "city": "Los Angeles"},
{"name": "Robert", "age": 45, "city": "Manhattan"},
{"name": "Sarah", "age": 31, "city": "New York"}
]
}
# Query using text format
output_text = jsonquery(data, """
.friends | filter(.city == "New York") | sort(.age) | pick(.name, .age)
""")
print("Text Query Result:")
pprint(output_text)
# Query using JSON format
output_json = jsonquery(data, [
"pipe",
["get", "friends"],
["filter", ["eq", ["get", "city"], "New York"]],
["sort", ["get", "age"]],
["pick", "get", "name"], ["get", "age"]
])
print("\nJSON Query Result:")
pprint(output_json)
# Example of parsing and stringifying
from jsonquerylang import parse, stringify
text_query = '.friends | filter(.age > 20)'
parsed_query = parse(text_query)
print(f"\nParsed query: {parsed_query}")
round_tripped_text = stringify(parsed_query)
print(f"Round-tripped text: {round_tripped_text}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jsonquery'
Attempting to import from the old or conflicting `jsonquery` module name.
fixChange your import statement from `from jsonquery import ...` to `from jsonquerylang import ...`.
Error: Cannot read properties of null (reading 'city')
Attempting to access a nested property on a null or non-existent parent property. JSON Query properties support optional chaining, returning null for non-existent intermediate properties, but subsequent operations on this null will fail.
fixEnsure that all intermediate properties in a path exist, or use `filter()` to remove objects where the path would resolve to null before attempting further access. For example, `.users | filter(.address.city != null) | map(.address.city)`.
QueryParseError: Syntax error: Unexpected token ')'
Often caused by incorrect parentheses usage, such as an unmatched parenthesis or an attempt to use parentheses for array indexing (e.g., `array(0)` instead of `array.0` or `get(0)`), or missing parentheses around complex conditions.
fixReview the query syntax for correct parentheses balancing, especially in filters or complex expressions. Remember array item access is `.index` or `get(index)`, not `(index)`.
Upgrade
Version history
2.1.0latest on PyPI · released Dec 9, 2025
Audit
Dependencies
No dependency data recorded yet.