jq (Python bindings)

1.11.0 · active · verified Thu Apr 09

jq is a lightweight and flexible JSON processor. This Python library provides robust bindings to the native `jq` C library (version 1.8.1), allowing Python applications to compile and execute `jq` programs for efficient JSON manipulation, filtering, and transformation. Currently at version 1.11.0, the project maintains an active release cadence with regular updates.

Warnings

deprecated The `input()` method on compiled `jq` programs is older and deprecated. It can accept a valid JSON value as a positional argument or unparsed JSON text via the `text` keyword argument.
Fix: Use `input_value()` for valid Python JSON values, `input_text()` for raw JSON strings, and `input_values()` for iterable sequences of Python JSON values. These methods offer clearer intent and better error handling.
gotcha When `pip install jq` is performed without pre-built wheels available for your specific Python version and architecture, the package attempts to build from source. This requires native development tools (e.g., `autoconf`, `automake`, `libtool`, `build-essential` on Linux, Xcode command line tools on macOS) and Python development headers to be installed on your system.
Fix: Ensure the necessary system-level build dependencies are installed before running `pip install jq`. Alternatively, set the environment variable `JQPY_USE_SYSTEM_LIBS=1` during installation to link against a pre-installed system `libjq` and `libonig` (requires these libraries to be available on the system).
gotcha There are multiple Python bindings for `jq`, notably `jq` (mwilliamson/jq.py) and `pyjq` (doloopwhile/pyjq). These libraries are incompatible and have different APIs. Accidentally installing or importing the wrong one can lead to unexpected errors.
Fix: Be mindful of which `jq` binding you intend to use. This entry pertains to `mwilliamson/jq.py`, installed via `pip install jq`. If using `pyjq`, refer to its specific documentation and `pip install pyjq`.
gotcha Certain `jq` language constructs, such as `first`, `last`, `nth(n)`, and excessive `slurping` without proper optimization, can lead to inefficient or unexpected behavior in complex `jq` programs, especially with large datasets.
Fix: Review `jq` best practices for performance. Avoid recomputing intermediate results, use variables (`$var`) for caching where appropriate, and prefer simpler filters or Python-side logic if `jq` expressions become overly complex or inefficient.

Install

pip install jq Standard installation
sudo apt-get install autoconf automake build-essential libtool python3-dev && pip install jq Source build (Debian/Ubuntu)

Imports

jq
```
import jq
```

Quickstart

This quickstart demonstrates compiling a `jq` program and applying it to both single JSON values and lists of values using the recommended `input_value()` and `input_values()` methods. It then retrieves the first or all results.

import jq

json_data = {"name": "Alice", "age": 30, "city": "New York"}

# Compile a jq program to extract the name and add a greeting
compiled_program = jq.compile(".name | ""Hello, \(. )!""")

# Process a single JSON value
result = compiled_program.input_value(json_data).first()
print(result)

# Example with a list of values
list_data = [{"value": 1}, {"value": 2}]
compiled_list_program = jq.compile(".value + 10")
results_list = compiled_list_program.input_values(list_data).all()
print(results_list)

view raw JSON →