---
id: jq
version: "1.12.0"
license: BSD-2-Clause
license_treatment: permissive
maintenance: active
---

# jq — jq is a lightweight and flexible JSON processor.

License: permissive · Maintenance: active · Downloads: 7.0M/mo

## What it is and what it does

jq is a Python wrapper around the jq JSON query language (version 1.8.2), letting you write jq programs in Python and apply them to JSON data. It compiles a jq program string into an executable object, then chains input methods (input_value, input_values, input_text) to supply data and output methods (first, all, text, iter) to retrieve results. The package handles both parsed JSON values and raw JSON text, supports multiple outputs per query, and allows passing variables into programs via the args parameter.

The main use case is querying and transforming JSON structures using jq's expressive filter syntax without shelling out to the jq command-line tool. It has no runtime dependencies beyond the compiled jq library itself, and prebuilt wheels cover most common platforms and Python versions, though building from source on unsupported platforms requires a C toolchain.

Use it for:

- Extract and transform JSON data in data pipelines using jq's filter syntax instead of manual dict manipulation.
- Parse streaming JSON text (newline-delimited or slurped) and apply complex queries in a single call.
- Integrate jq programs written for command-line use into Python applications without subprocess overhead.
- Filter and reshape nested JSON structures with jq's array/object operators and built-in functions.
- Build JSON query tools that accept jq program strings as user input and execute them safely.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Python bindings for jq 1.8.2 that let you compile and execute jq programs against JSON data, with multiple input and output methods.

Yes. jq is actively maintained, has no known vulnerabilities, runs on current Python versions, and offers prebuilt wheels for common platforms. Install friction is moderate but manageable. Use it if you need jq's query language in Python; if you only need basic JSON manipulation, the standard library json module may suffice.

## Install

pip install jq
uv add jq
poetry add jq

## Installing jq

Before you install: Medium install friction: prebuilt wheels exist for Python 3.8–3.14 on Linux, macOS, and Windows, but fallback source builds require autoconf, libtool, a C compiler, and Python headers. Set JQPY_USE_SYSTEM_LIBS=1 to use system libjq instead of building it.

License in practice: BSD-2-Clause is permissive; you may use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install jq

import jq

result = jq.compile(".+5").input_value(42).first()
assert result == 47

If no prebuilt wheel is available, building from source requires autoconf, libtool, a C compiler, and Python development headers.

Verify before relying:

- Whether jq 1.8.2 is the latest upstream version or if newer versions are available
- Performance characteristics compared to other JSON query libraries in Python
- Whether PyPy support is actively tested or only declared

## Package facts

- License: BSD-2-Clause (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 7.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

jq json processor python, json query language python, jq bindings, json filtering python, jq program execution, json-query, data-transformation

[View on SkillFed](https://skillfed.io/packages/jq) · [View on PyPI](https://pypi.org/project/jq/)