jq 1.8.2: a plain C JSON filter that still sets the bar for one-liners
Command-line JSON processor
At a glance
- What is it?
- jq is a zero-dependency C program for slicing, filtering, and transforming JSON from the command line. This review covers what it does, how to run it, where it falls short, and who should skip it.
- Who is it for?
- Adopt jq if you work with JSON in shell scripts or need a fast, dependency-free way to extract and reshape data on any Unix-like system. Skip it if you need complex in-place editing or a GUI.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly C, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- jqlang/jq36,136 ★ · +676
| Repository | 2026-08-18 | 2026-11-15 |
|---|---|---|
| jqlang/jq | 35.5k | 36.1k |
676 Stars in the last 89 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What jq actually is and who needs it
jq is a command-line JSON processor, comparable to sed, awk, and grep for structured data. It is written in portable C and has zero runtime dependencies, which means you can drop it onto a minimal container or a bare server without pulling in a language runtime. The target user is anyone who needs to extract a field, filter an array, or reshape a JSON document inside a shell pipeline. That includes DevOps engineers parsing API responses, data analysts cleaning export files, and developers debugging local JSON. The README frames it as lightweight and flexible, and the zero-dependency claim is the core promise. If you already have a JSON document and you want to answer a question about it without writing a Python script, jq is the tool designed for that exact moment.
The mechanism: filters, pipes, and the stream model
jq works by applying a filter to each JSON value in its input. The filter language is a small functional DSL: you write expressions that select fields with `.field`, index arrays with `.[0]`, and chain operations with a pipe symbol, `|`. The output is a stream of JSON values, one per input value, unless the filter itself produces multiple outputs. This is the same mental model as Unix text filters: input comes in, a transformation happens, output goes out. The README gives a concrete example: `docker run --rm -i ghcr.io/jqlang/jq:latest < package.json '.version'` extracts the version field from a package.json file. The input is read from standard input, the filter is the string `'.version'`, and the result is printed to standard output. That is the whole data flow. There is no persistent state, no server, no daemon. Each invocation is a one-shot transformation. The power comes from composing small filters, not from any complex architecture.
Getting it running: binaries, Docker, and a source build
There are three supported ways to run jq. The simplest is to download a prebuilt binary from the GitHub release page. The README points there first, and it is the fastest path for most users. The second is Docker: `docker run --rm -i ghcr.io/jqlang/jq:latest < package.json '.version'` reads JSON from standard input, and a variant with `-v "$PWD:$PWD" -w "$PWD"` mounts the current directory so you can pass a file as an argument, like `'.version' package.json`. The third is building from source. The dependencies are libtool, make, automake, and autoconf. If you clone from git, you must run `git submodule update --init` to get oniguruma, then `autoreconf -i`, then `./configure --with-oniguruma=builtin`. The README warns to run `make clean` if you are upgrading from a previous source build. For a statically linked binary, use `make LDFLAGS=-all-static`. If you build from a release tarball instead of git, you can skip `autoreconf` and you will not need flex or bison. That distinction matters: the git build pulls in more tooling than the tarball build.
Where jq is the wrong tool
jq is also not a general-purpose programming language. If your transformation logic involves complex state, external API calls, or non-JSON output formats, you will fight the filter language. Another limitation: jq is read-only in the sense that it cannot modify a file in place. You have to redirect output to a new file and move it over the original. That is standard Unix behaviour, but it surprises people coming from tools that edit files directly. Finally, the filter syntax has a learning curve. Simple field access is trivial, but anything involving `reduce`, `foreach`, or custom functions requires reading the manual. The README does not include a tutorial, so new users must rely on the official documentation site or Stack Overflow.
The alternative: yq or a Python one-liner
If jq does not fit, the most direct alternative is yq, a YAML processor that often mimics jq's syntax but works on YAML input. The difference in approach is the input format: yq parses YAML, which is a superset of JSON, so it can handle JSON files too, but it is a separate project with its own dependencies and quirks. For pure JSON, a Python one-liner using `json` and `sys.stdin` is a common fallback. The difference there is that Python gives you a full programming language, so you can do multi-step transformations without learning a new DSL. But Python is not a single static binary; it requires a Python interpreter, which may not be present on a minimal system. That is exactly the trade-off jq addresses: a single C binary with no runtime dependencies versus a heavier but more flexible runtime. If you only ever touch JSON, jq is the lighter choice. If you also touch YAML, yq reduces the number of tools you need. The choice depends on your input formats and your tolerance for installing a second tool.
Maintenance, releases, and licence notes
The repository is active. The last push was on 2026-11-02, and there are three recent releases: 1.8.0 in June 2025, 1.8.1 in July 2025, and 1.8.2 in June 2026. That cadence suggests steady maintenance, but the gap between 1.8.1 and 1.8.2 was nearly a year, so do not expect rapid feature releases. The project uses a default branch named master, which is a minor detail but worth noting for people who prefer main. On licensing, the README states jq is released under the MIT License, but the repository metadata says NOASSERTION. That discrepancy is worth checking before you distribute a modified binary. The documentation is licensed under Creative Commons CC BY 3.0, and the project includes parts of the decNumber library, which is under the ICU License. The MIT licence is permissive, but the bundled decNumber code means you are not shipping a purely MIT codebase. Read the COPYING file in the repository to understand the exact terms for your use case.
Editorial conclusion
Adopt jq if you work with JSON in shell scripts or need a fast, dependency-free way to extract and reshape data on any Unix-like system. Skip it if you need complex in-place editing or a GUI. Before adopting, verify the exact version you install: 1.8.2 is current, but older distro packages may lack recent fixes. Check the release notes for any changes that affect your filters, and test your jq expressions against the version you will actually run.
Frequently asked questions
What is the jq command in jqlang/jq?
jq is a lightweight and flexible command line JSON processor akin to sed, awk and grep for JSON data, written in portable C with zero runtime dependencies for slicing, filtering, mapping and transforming structured data.
How do you use the jq command against JSON files?
Read the official documentation at jqlang.org, experiment in the browser at play.jqlang.org, and run filters such as .version against local files through a downloaded binary or the published Docker image.
How do you query JSON with jq filters?
Point jq at a file and a filter expression, for example extracting the .version field from a package.json file either with input redirection or by passing the file path as an argument.
What is jqlang/jq for JSON processing?
jqlang/jq is the repository home of jq, with documentation at jqlang.org, an online playground at play.jqlang.org, and releases published from the GitHub release page.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/jqlang-jq)Star history chart for your README
[](https://hysenlabs.com/projects/jqlang-jq)Was this useful?