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.
pip install jqVerified import paths — ran on the pinned version, not inferred.
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.
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.
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).
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`.
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 the package using pip: `pip install jq`.
Review your JSON data structure and the jq program. If the data is an array, use integer indices (e. [0]) or the array iterator (e.g., .[]). If the field might be optional or sometimes an array/object, use the optional operator (e.g., .id?) or type checking (e.g., if type=="array" then .[] else .id end).
Carefully check the jq program string for syntax errors. Test the jq expression on the command line first to ensure it's valid before using it in Python.
Ensure that the input data passed to `input_value()` or other input methods is valid JSON. Use a JSON validator or `json.loads()` in Python to identify and fix issues like missing commas, unquoted keys, or incorrect data types.