pyjq - Python Binding for jq

2.6.0 · active · verified Fri Apr 17

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.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'jq'
```
cause The `jq` command-line executable is not installed on your system or is not located in any directory listed in your system's PATH environment variable.

fix Install `jq` on your operating system. For example: `sudo apt-get install jq` (Debian/Ubuntu), `brew install jq` (macOS), `choco install jq` (Windows), or `dnf install jq` (Fedora).
```
AttributeError: module 'pyjq' has no attribute 'first'
```
cause The `pyjq.first()` helper function was removed in `pyjq` version 2.0.0.

fix Replace `pyjq.first(query, data)` with `next(pyjq.jq(query, data))` or, for explicit single result retrieval, `pyjq.jq(query, data, first_result=True)`.
```
AttributeError: module 'pyjq' has no attribute 'all'
```
cause The `pyjq.all()` helper function was removed in `pyjq` version 2.0.0.

fix Replace `pyjq.all(query, data)` with `pyjq.jq(query, data, all_results=True)` or `list(pyjq.jq(query, data))` to obtain all results as a list.
```
TypeError: 'generator' object is not subscriptable
```
cause `pyjq.jq()` returns a generator (iterator) object by default for queries that can produce multiple results in `pyjq` 2.x. You are attempting to access it using list-like indexing `[]`.

fix If you expect multiple results, convert the generator to a list: `results = list(pyjq.jq(query, data))` or use `pyjq.jq(query, data, all_results=True)`. If you expect a single result, retrieve it with `result = next(pyjq.jq(query, data))`.

Warnings

gotcha The `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`.
breaking In `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))`.
gotcha For `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))`.
gotcha Incorrect `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.

Install

pip install pyjq Install pyjq

Imports

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

Quickstart

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)}")

view raw JSON →