gojq: jq in Go, and How It Differs
gojq is a pure-Go reimplementation of jq that keeps the filter language but sorts object keys by default, reports clearer errors, and adds some builtins.
gojq is popular because it is a single static Go binary and embeddable. It is highly jq-compatible, with a few documented behavior changes worth knowing before you swap it in.
What it does
gojq evaluates jq filters over JSON with the standard flags. Notable differences from jq: it keeps object keys sorted by default (jq preserves input order unless told otherwise), produces more precise error messages, and adds builtins, while not depending on the C jq library.
Common usage
# same invocation as jq
echo '{"b":2,"a":1}' | gojq '.'
# raw, compact output
gojq -rc '.users[].email' data.json
# pass JSON argument
gojq --argjson n 3 '.items[:$n]' data.jsonOptions
| Flag | What it does |
|---|---|
| -r, --raw-output | Raw string output |
| -c, --compact-output | Compact JSON |
| -n, --null-input | Null as the input |
| -s, --slurp | Slurp inputs into one array |
| --arg / --argjson | Bind string / JSON variables |
| --yaml-input / --yaml-output | Read or write YAML (gojq extension) |
In CI
gojq's single static binary is easy to vendor into a minimal container with no shared-library dependencies, and its --yaml-input/--yaml-output flags let one tool handle both JSON and YAML. Its clearer error messages also make a failing CI filter quicker to diagnose.
Common errors in CI
gojq: command not found: go install github.com/itchyny/gojq/cmd/gojq@latest or a release binary. The most common surprise is reordered output: gojq sorts object keys, so a test that diffs against jq's input-order output fails; account for the ordering or sort both sides. gojq raises errors (for example on null indexing in some cases) where jq stayed silent, which is stricter by design. The error-on-... differences mean a script tolerant of jq's leniency may need adjusting.