Registry / serialization / pyjq
library2.6.0pypypiunverified

pyjq is a Python binding for the `jq` command-line JSON processor. It allows executing `jq` queries against Python dictionaries and lists, providing flexible and powerful JSON data manipulation capabilities. As of version 2.6.0, it primarily offers a `jq()` function with options for single or multiple results, as well as a `run()` function for CLI-like behavior. It is actively maintained with regular updates.

pip install pyjq
INSTALL
IMPORT
SIG · PYJQ
P
pyjq
serializationpythonv2.6.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
build_error
glibc
py 3.103.910 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

jq
import pyjq
The primary function for querying Python objects is `pyjq.jq`. For CLI-like string processing, `pyjq.run` is used.

This quickstart demonstrates how to use `pyjq.jq()` to query Python dictionaries, including how to handle multiple results with `all_results=True`. It also shows `pyjq.run()` for processing raw JSON string inputs, mimicking the `jq` CLI.

import pyjq import json data = { "items": [ {"name": "Apple", "price": 1.0, "category": "Fruit"}, {"name": "Banana", "price": 0.5, "category": "Fruit"}, {"name": "Carrot", "price": 0.3, "category": "Vegetable"} ] } # Select names of all fruits, returning a list of results fruit_names = pyjq.jq('.items[] | select(.category == "Fruit") | .name', data, all_results=True) print(f"Fruit names: {list(fruit_names)}") # Get the price of the first item (returns an iterator by default) # Use next() to get the first value from the iterator first_item_price_iterator = pyjq.jq('.items[0].price', data) print(f"First item price (iterator): {next(first_item_price_iterator)}") # Using pyjq.run for CLI-like behavior, processing a JSON string json_string = json.dumps(data) all_prices_iterator = pyjq.run('.items[].price', text_input=json_string) print(f"All prices (from string input): {list(all_prices_iterator)}")
Debug
Known issues
gotchaThe `jq` executable is a mandatory system dependency. `pyjq` does not bundle `jq` itself; it acts as a wrapper around the installed `jq` command-line tool.
fix
Ensure `jq` is installed on your operating system (e.g., `sudo apt-get install jq` on Debian/Ubuntu, `brew install jq` on macOS, `choco install jq` on Windows) and accessible in your system's PATH before using `pyjq`.
affects: All versions
breakingIn `pyjq` 2.x, the standalone helper functions `pyjq.first()` and `pyjq.all()` were removed in favor of parameters on the main `pyjq.jq()` function.
fix
Use the `pyjq.jq()` function directly with the `all_results=True` or `first_result=True` parameters. For example, replace `pyjq.all(query, data)` with `pyjq.jq(query, data, all_results=True)` and `pyjq.first(query, data)` with `pyjq.jq(query, data, first_result=True)` or `next(pyjq.jq(query, data))`.
affects: 2.0.0 and later
gotchaFor `jq` expressions that can return multiple values (e.g., `.[][]` or `.[].name`), `pyjq.jq()` returns an iterator/generator object by default in `pyjq` 2.x.
fix
To get all results as a list, convert the iterator: `list(pyjq.jq(query, data))`, or pass `all_results=True` to the `jq()` function: `pyjq.jq(query, data, all_results=True)`. If you expect a single result, use `next()`: `next(pyjq.jq(query, data))`.
affects: 2.0.0 and later
gotchaIncorrect `jq` query syntax, non-JSON data types as input, or `jq` errors can raise `pyjq.PyjqException` or `subprocess.CalledProcessError`.
fix
Always ensure your input data is JSON-serializable (dict, list, str, int, bool, None). Validate `jq` query syntax, perhaps using the `jq` CLI first. Wrap `pyjq` calls in `try...except pyjq.PyjqException` for robust error handling.
affects: All versions
Upgrade
Version history
2.6.0latest on PyPI · released Aug 2, 2022
Audit
Dependencies
jqrequiredpyjq is a binding for the 'jq' command-line tool. The 'jq' executable must be installed and available in your system's PATH for pyjq to function.
Agent activity
9 hits · last 30 days
node
8
Resources
pyjq — pip install pyjq · libregistry