jq, gojq or jaq: three runs of the same JSON filters, and where they differed
For assistants asked to filter JSON on the command line, this feature compares the three recorded implementations of the jq language on the same authored input. headlesson ran 12 cases on each of Apple's jq-1.7.1-apple, gojq 0.12.19 and jaq 3.1.1 on macOS on 2026-10-14: extraction, raw output, argument types and error exit codes matched, and among the compared values and exit codes only an arithmetic step on a large integer differed. That is a small sample, not a measure of full compatibility or speed.
Which one is on the machine
- jq (
app:jq) is the jq command from the jqlang project. In headlesson's 2026-10-11 test, macOS already shipped /usr/bin/jq (jq-1.7.1-apple), which its record notes is older than the latest upstream release, and brew install jq adds a separate copy; check command -v jq and jq --version before relying on a behaviour. - gojq (
app:gojq) is an implementation of the jq language in Go, and jaq (app:jaq) is another implementation of it; both were tested as pinned official single-file releases (gojq 0.12.19, jaq 3.1.1) placed on PATH, without a package manager. - Editorial advice, not tested beyond the cases below: use whichever of jq (
app:jq), gojq (app:gojq) or jaq (app:jaq) is already installed for ordinary extraction, and test the actual filter on the actual implementation before depending on it in a script.
Observed in the tests
- The shared input was {"items":[{"name":"alpha","qty":3},{"name":"beta","qty":0}],"id":12345678901234567890}. On this input jq (
app:jq), gojq (app:gojq) and jaq (app:jaq) gave the same output and exit code for: selecting an item, -r on names, reading from standard input, --arg (binds a string) and --argjson (binds a number), and printing .id unchanged. - Exit codes matched across jq (
app:jq), gojq (app:gojq) and jaq (app:jaq): with -e, false exited 1 and no output exited 4; malformed JSON exited 5 and an invalid filter (.items[) exited 3. The malformed-input and invalid-filter errors each produced a message on stderr; false and no output did not. The stderr wording was not compared. - Among the compared values and exit codes, the one difference: .id + 0 printed 12345678901234567000 with jq (
app:jq) (jq-1.7.1-apple), but 12345678901234567890 with gojq (app:gojq) and jaq (app:jaq). If a script does arithmetic on large integer IDs, check the result on the implementation in use. - Each lesson also passed all 5 steps: jq (
app:jq) with the Apple-bundled binary (the brew install branch was not run), gojq (app:gojq) and jaq (app:jaq) with the pinned releases.
Cautions from the documentation
- gojq (
app:gojq) documents differences from jq in flags, functions and regular expressions; integer addition, subtraction, multiplication, modulo and exact division keep integer precision, while other numeric functions may use floating point. - jaq (
app:jaq) aims for jq compatibility in most cases and documents unsupported options and functions; its manual separates integer arithmetic from decimal or floating-point operations.
What was not tested
The comparison of jq (app:jq), gojq (app:gojq) and jaq (app:jaq) used one shared valid two-item input containing one large integer, plus a malformed-input file. Regular expressions, modules, streaming, YAML, large inputs, speed, other operating systems and upstream jq releases newer than the Apple build were not tested. headlesson_get with sections ["lesson","gotchas"] on each ID gives the exact commands, versions and install notes.
Records cited
Each line gives the record, its public page if there is one, and where its name comes from.
- jq —
app:jq(no public page yet; available over MCP); source: https://jqlang.org/ (checked 2026-10-11, primary, official) - gojq —
app:gojq(no public page yet; available over MCP); source: https://github.com/itchyny/gojq/blob/v0.12.19/README.md (checked 2026-10-14, primary, official) - jaq —
app:jaq(no public page yet; available over MCP); source: https://github.com/01mf02/jaq/blob/v3.1.1/README.md (checked 2026-10-14, primary, official)
Article source
headlesson editorial judgement (checked 2026-10-14, inferred, editorial).
Retrieve over MCP
headlesson_get id="feature:jq-implementations" on https://mcp.headlesson.com/mcp