jq

jq is a small but surprisingly powerful command-line tool — and a complete domain-specific programming language — for working with JSON. You hand it a stream of JSON and a filter, and it produces a transformed stream of JSON. Its own documentation describes it as being “like sed for JSON data”: you can slice, filter, map, and reshape structured data with the same kind of terse, composable expressions that make sed and awk indispensable for plain text. First released by Stephen Dolan in 2012, jq has become a near-universal fixture of shell scripts, CI/CD pipelines, and cloud tooling — the tool reached for the moment a command spits out JSON that needs to be queried or reshaped.

History & Origins

jq was created by Stephen Dolan and first appeared in 2012. The motivation was a familiar one: the Unix command line had decades of excellent text-processing tools — grep, sed, awk, cut — but they all treat input as flat streams of lines and characters. As JSON became the lingua franca of web APIs and configuration, piping that JSON through line-oriented tools was awkward and error-prone. jq filled the gap by treating JSON values as its native unit of work rather than lines of text.

A frequently repeated detail of jq’s history is that the language was first prototyped in Haskell before being rewritten in portable C with no runtime dependencies. That choice paid off: a single, dependency-free C binary is trivial to install everywhere, which is a large part of why jq spread so quickly into scripts, container images, and CI environments.

For its first several years jq was effectively a one-maintainer project, and after the 1.6 release in 2018 it went quiet for nearly five years. In 2023 the project was revived: it moved to a dedicated jqlang GitHub organization, the original repository was transferred from Stephen Dolan, and an expanded team of maintainers shipped the long-awaited 1.7 release. Development has continued steadily since, through the 1.8 series in 2025.

Design Philosophy

jq is built around a single, elegant idea: everything is a filter, and filters compose with a pipe.

• Filters, not statements. A jq program is a filter — a function from an input value to a (possibly empty, possibly multiple-valued) stream of output values. The identity filter . simply emits its input unchanged.
• Composition with |. Just like the Unix shell pipe, jq’s | feeds the output of one filter into the next. .users | .[] | .name walks into the users field, iterates the array, and pulls out each name.
• Streams of values. Filters don’t return a single result; they produce a stream. A filter like .[] emits each element of an array in turn, and downstream filters run once per value. This stream model is what makes jq concise — much of the iteration is implicit.
• Purely functional. jq has no mutable variables in the imperative sense and no side effects on its data. You describe transformations declaratively, and jq applies them.
• Tacit, point-free style. Because the input is always the implicit ., many jq programs never name their data at all, reading almost like a path expression.

This design makes simple things very short — jq '.name' extracts a field — while still scaling up to genuinely complex transformations.

Key Features

Filters and pipelines

The core of jq is field access, array iteration, and piping:

1
2
3
4
5

# Extract the name of every user
echo '{"users":[{"name":"Ada"},{"name":"Linus"}]}' \
  | jq '.users[].name'
# "Ada"
# "Linus"

Constructing new JSON

jq can build new objects and arrays, not just extract values:

1
2

# Reshape each user into a new object
jq '.users | map({user: .name, active: true})'

Built-in functions and the standard library

jq ships with a rich set of builtins — map, select, group_by, sort_by, unique, min, max, add, length, keys, to_entries, from_entries, and many more — that cover most data-wrangling needs:

1
2

# Keep only active users, then list their names sorted
jq '[.users[] | select(.active)] | sort_by(.name) | map(.name)'

Variables, reductions, and control flow

While jq leans functional, it provides as bindings, if/then/elif/else/end, reduce, and foreach for accumulation and conditional logic:

1
2

# Sum a list of numbers with reduce
jq 'reduce .[] as $n (0; . + $n)'

Regular expressions and modules

Since jq 1.5, the language has included regular-expression support (via the Oniguruma engine) through functions like test, match, capture, sub, and gsub, along with a module system for sharing reusable definitions.

Turing completeness

Although it is a domain-specific language, jq is Turing-complete — a fact demonstrated playfully by community projects such as Brainfuck interpreters written entirely in jq. In practice this means jq can express recursion and arbitrary computation, even though its sweet spot remains data transformation.

Evolution

jq’s influence is also visible in its reimplementations. gojq, written in Go by itchyny (with first public versions appearing around 2019), reimplements much of the language and adds conveniences like YAML support, and it has been embedded in other tools. jaq, a Rust implementation by Michael Färber, was developed alongside a formal, denotational semantics for the language and focuses on correctness and speed. The existence of multiple independent implementations is a sign that jq’s expression language has become a small standard in its own right.

Current Relevance

jq is, today, one of the most widely deployed command-line tools that most users never think of as a “programming language.” It is pre-installed on common CI runners, recommended in major cloud vendors’ CLI documentation, packaged in virtually every Linux distribution and Homebrew, and bundled into countless container images. Whenever a tool emits JSON and a human needs to pick it apart in a shell, jq is the default answer.

The 2023 revival under the jqlang organization put the project back on a healthy footing after years of stagnation, and the 1.7 and 1.8 release lines show active, security-conscious maintenance. Meanwhile, alternative implementations like gojq and jaq keep the language ecosystem competitive and push performance and correctness forward.

Why It Matters

jq matters because it brought the Unix pipeline philosophy into the age of structured data. The classic text tools — grep, sed, awk — assume the world is made of lines; jq assumes the world is made of JSON values, and it preserves the same composable, do-one-thing-well spirit. In doing so it made JSON a first-class citizen of the command line and demonstrated that a tightly scoped, purely functional domain-specific language can become genuinely indispensable infrastructure. For a tool that fits in a single dependency-free binary, jq has had an outsized impact on how developers and operators interact with the JSON that now underpins nearly every API and configuration system.