{"id":2080,"library":"jq","title":"jq (Python bindings)","description":"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.","status":"active","version":"1.11.0","language":"en","source_language":"en","source_url":"https://github.com/mwilliamson/jq.py","tags":["JSON","data processing","query","filter","cli-tool-binding"],"install":[{"cmd":"pip install jq","lang":"bash","label":"Standard installation"},{"cmd":"sudo apt-get install autoconf automake build-essential libtool python3-dev && pip install jq","lang":"bash","label":"Source build (Debian/Ubuntu)"}],"dependencies":[{"reason":"The Python `jq` package provides bindings to the native `jq` C library. While pre-built wheels typically bundle this C library, installing from source or explicitly setting `JQPY_USE_SYSTEM_LIBS=1` will require a system-wide installation of `libjq` and `libonig`.","package":"jq (C library)","optional":true}],"imports":[{"symbol":"jq","correct":"import jq"}],"quickstart":{"code":"import jq\n\njson_data = {\"name\": \"Alice\", \"age\": 30, \"city\": \"New York\"}\n\n# Compile a jq program to extract the name and add a greeting\ncompiled_program = jq.compile(\".name | \"\"Hello, \\(. )!\"\"\")\n\n# Process a single JSON value\nresult = compiled_program.input_value(json_data).first()\nprint(result)\n\n# Example with a list of values\nlist_data = [{\"value\": 1}, {\"value\": 2}]\ncompiled_list_program = jq.compile(\".value + 10\")\nresults_list = compiled_list_program.input_values(list_data).all()\nprint(results_list)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"deprecated","affected_versions":"<1.5.0 (for primary use), but generally discouraged in all newer versions."},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions, when wheels are not available."},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions, due to naming collision."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (pertains to `jq` language efficiency)."}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}