gitwtfhub

wtf is gojq?

itchyny/gojq — explained in plain English

Analysis updated 2026-07-03

3,754GoAudience · developerComplexity · 2/5LicenseSetup · easy

TL;DR

Gojq is a pure-Go rewrite of jq that filters and transforms JSON and YAML from the command line or inside Go programs, with no C library dependencies and better handling of large integers.

Mindmap

mindmap
  root((gojq))
    What it does
      Filter JSON
      Transform data
      Query YAML
    Use Cases
      CLI scripting
      Go library embed
      API data extraction
    Advantages
      No C dependencies
      Large integer support
      Clear error messages
    Tech Stack
      Go
      JSON
      YAML

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Pipe API responses through gojq on the command line to extract specific fields or reshape nested JSON without writing a script.

REASON 2

Import gojq as a Go library to run jq-style queries inside your own application without shelling out to an external binary.

REASON 3

Process YAML configuration files from the terminal using familiar jq syntax without a separate YAML tool.

REASON 4

Handle API responses containing very large integer IDs without the rounding errors that the original jq produces.

What's in the stack?

GoJSONYAML

How it stacks up

itchyny/gojqoffchainlabs/prysmqax-os/elastichd
Stars3,7543,7553,755
LanguageGoGoGo
Setup difficultyeasyhardeasy
Complexity2/54/52/5
Audiencedeveloperops devopsops devops

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · easy Time to first run · 5min
Use, modify, and distribute freely for any purpose including commercial projects, with the copyright notice retained.

Wtf does this do

Gojq is a rewrite of the popular command-line tool jq, built entirely in Go. The original jq is a widely-used program that lets you slice, filter, and transform JSON data from the terminal. Gojq does the same thing but is built without any C library dependencies, which makes it easier to compile and distribute across different operating systems without worrying about system library compatibility. From the command line, you pipe JSON text into gojq and write a short query expression to extract or reshape the data. For example, you can pull a specific field out of a JSON object, loop over an array and print each item, or do arithmetic on numeric values, all in a single line. Error messages are designed to show exactly where a query went wrong, which makes it easier to fix mistakes without guessing. Installation is available through Homebrew on macOS, through Docker, or by building from the Go source directly. For developers writing Go programs, gojq can also be imported as a library, letting you run jq-style queries against JSON data inside your own application code rather than shelling out to an external command. Compared to the original jq, gojq handles large integers without rounding errors, reads and writes YAML in addition to JSON, and fixes several edge cases around date formatting and string handling. It intentionally leaves out a handful of flags and functions from the original jq, mostly ones related to output ordering or rarely-used features, and the README documents each omission clearly. The project is licensed under MIT and is suitable for both personal scripting and embedding in production Go applications.

Yoink these prompts

Prompt 1
Using gojq on the command line, show me how to extract the name field from every object in a JSON array returned by a curl request.
Prompt 2
I'm writing a Go service that receives JSON payloads. Show me how to import gojq as a library and run a query to pull a nested field value.
Prompt 3
I have a YAML config file with a list of servers. Write a gojq command to filter only servers where the enabled field is true and print their names.
Prompt 4
Show me the difference in output between jq and gojq when parsing a JSON number larger than 2 to the power of 53, and explain why gojq handles it correctly.

Frequently asked questions

wtf is gojq?

Gojq is a pure-Go rewrite of jq that filters and transforms JSON and YAML from the command line or inside Go programs, with no C library dependencies and better handling of large integers.

What language is gojq written in?

Mainly Go. The stack also includes Go, JSON, YAML.

What license does gojq use?

Use, modify, and distribute freely for any purpose including commercial projects, with the copyright notice retained.

How hard is gojq to set up?

Setup difficulty is rated easy, with roughly 5min to a first successful run.

Who is gojq for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.