{"id":10101,"library":"pyjq","title":"pyjq - Python Binding for jq","description":"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.","status":"active","version":"2.6.0","language":"en","source_language":"en","source_url":"https://github.com/doloopwhile/pyjq","tags":["json","jq","query","data-processing","cli-binding"],"install":[{"cmd":"pip install pyjq","lang":"bash","label":"Install pyjq"}],"dependencies":[{"reason":"pyjq 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.","package":"jq","optional":false}],"imports":[{"note":"The primary function for querying Python objects is `pyjq.jq`. For CLI-like string processing, `pyjq.run` is used.","symbol":"jq","correct":"import pyjq"}],"quickstart":{"code":"import pyjq\nimport json\n\ndata = {\n    \"items\": [\n        {\"name\": \"Apple\", \"price\": 1.0, \"category\": \"Fruit\"},\n        {\"name\": \"Banana\", \"price\": 0.5, \"category\": \"Fruit\"},\n        {\"name\": \"Carrot\", \"price\": 0.3, \"category\": \"Vegetable\"}\n    ]\n}\n\n# Select names of all fruits, returning a list of results\nfruit_names = pyjq.jq('.items[] | select(.category == \"Fruit\") | .name', data, all_results=True)\nprint(f\"Fruit names: {list(fruit_names)}\")\n\n# Get the price of the first item (returns an iterator by default)\n# Use next() to get the first value from the iterator\nfirst_item_price_iterator = pyjq.jq('.items[0].price', data)\nprint(f\"First item price (iterator): {next(first_item_price_iterator)}\")\n\n# Using pyjq.run for CLI-like behavior, processing a JSON string\njson_string = json.dumps(data)\nall_prices_iterator = pyjq.run('.items[].price', text_input=json_string)\nprint(f\"All prices (from string input): {list(all_prices_iterator)}\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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))`.","message":"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.","severity":"breaking","affected_versions":"2.0.0 and later"},{"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))`.","message":"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.","severity":"gotcha","affected_versions":"2.0.0 and later"},{"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.","message":"Incorrect `jq` query syntax, non-JSON data types as input, or `jq` errors can raise `pyjq.PyjqException` or `subprocess.CalledProcessError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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).","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'jq'"},{"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)`.","cause":"The `pyjq.first()` helper function was removed in `pyjq` version 2.0.0.","error":"AttributeError: module 'pyjq' has no attribute 'first'"},{"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.","cause":"The `pyjq.all()` helper function was removed in `pyjq` version 2.0.0.","error":"AttributeError: module 'pyjq' has no attribute 'all'"},{"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))`.","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 `[]`.","error":"TypeError: 'generator' object is not subscriptable"}]}