jq slices and reshapes JSON from the shell with zero runtime

A sed style filter for JSON without a runtime to install

Log pipelines and API responses arrive as nested JSON, and grep alone mangles the structure. jq fills the slot that sed, awk and grep hold for plain text: a small command line JSON processor that slices, filters, maps and transforms structured data. Implementation is portable C with zero runtime dependencies, so the tool runs wherever the single executable lands. Primary language is C, default branch is master, and the homepage is https://jqlang.org. Official documentation lives at jqlang.org while play.jqlang.org offers a browser playground for trying filters without installing anything. Teams that shape JSON in shell scripts, CI jobs and container entrypoints are the audience. Anyone wanting a graphical JSON explorer should look elsewhere, because this project stays on the command line by design.

Release page binaries, container image or source for odd platforms

Three install routes cover different fleets, and each carries its own handling cost. Prebuilt binaries come from the GitHub release page as platform specific standalone executables rather than archives. On macOS and Linux the reader renames the download to jq and marks it executable with chmod +x jq. Docker users pull the jq image from the container registry and run it directly, which suits CI agents that already run containers. Source builds serve the rest, including anyone who needs a custom or fully static binary. Recent releases read jq 1.8.2 from 2026-06-20, jq 1.8.1 and jq 1.8.0, and the last push landed on 2026-09-27 with the repository not archived. Matching the route to the fleet up front avoids a mix of half installed copies later.

First version extraction through stdin or a mounted volume

The fastest local proof reads a version field out of a package.json file through the published container. No local binary is needed, only Docker and a shell sitting in the project directory. Feeding the file through stdin keeps the command short. The filter .version selects the field and the result prints to the terminal:

docker run --rm -i ghcr.io/jqlang/jq:latest < package.json '.version'

The container reads the file from stdin, applies the filter, and prints the value. Expect the version string from package.json on stdout, with nothing left behind on the host because --rm removes the container when the filter finishes.

Mounted volume variant of the same version readout

A second example covers the case where redirection is awkward and the file must be visible inside the container. The run mounts the working directory, sets it as the working directory, and passes the file path plus the filter as arguments:

docker run --rm -i -v "$PWD:$PWD" -w "$PWD" ghcr.io/jqlang/jq:latest '.version' package.json

Output matches the stdin variant: the version string on stdout. Readers on machines where the shell variable PWD behaves differently should confirm the mount resolves before trusting the result, since the page gives this exact form and no alternative.

Source builds assemble autoconf, oniguruma and make check

Compiling from a git checkout demands four named dependencies and a fixed step order. The dependency list reads libtool, make, automake and autoconf. A submodule fetch pulls in oniguruma, the regex library behind pattern matching, and autoreconf prepares the configure script. Configuration pins the builtin copy of that library. From there the classic sequence runs: an optional clean for stale trees, parallel build, test suite, then privileged install:

git submodule update --init    # if building from git to get oniguruma
autoreconf -i                  # if building from git
./configure --with-oniguruma=builtin
make clean                     # if upgrading from a version previously built from source
make -j8
make check
sudo make install

Readers building a released tarball instead of git skip the autoreconf step, and flex or bison will not be needed. A green make check means the binary is ready for the privileged install step, which places jq on the system path.

Static linking flag for a single file binary

Hosts that must carry the binary between machines get a fully static option. One flag changes the link step and removes runtime library surprises:

make LDFLAGS=-all-static

The repository Dockerfile shows the same instinct taken further. A Debian 12 slim builder configures with oniguruma builtin plus static flags, runs make check verbose, then copies only AUTHORS, COPYING and the jq binary into a scratch image whose entrypoint is the binary itself. Teams shipping minimal images can mirror that shape instead of carrying a build toolchain into production.

Manual rename and chmod leave fleet installs to the reader

Standalone downloads sound simple until a fleet of machines is involved. Each asset is a bare executable, not an archive and not a package, so every host needs the same manual routine: download the right platform asset, rename it to jq, and mark it executable. No checksum step, no signature step and no repository pinning appear in the page text, which leaves verification and repeat installs to the reader. A team of thirty laptops absorbs that cost once and forgets it. A rotating pool of CI agents pays it on every image rebuild. Where agents already run Docker, the published image removes the routine entirely, and that tradeoff should be settled before the first pipeline references a jq binary.

Skipped submodule steps, cross compilation pointers and license files

Git checkouts punish skipped steps in ways tarballs do not. Forgetting the submodule fetch starves the build of oniguruma, skipping autoreconf leaves no configure script, and rebuilding an old tree without make clean mixes stale objects into the new binary. The page states each guard inline, which helps, but only if the reader follows the sequence top to bottom. Cross compilation gets no steps at all here, only pointers to the GitHub Actions workflow file and a wiki page. License paperwork needs a glance too. Metadata reports NOASSERTION while the page releases the tool under the MIT License, documentation under Creative Commons CC BY 3.0, and the bundled decNumber code under the ICU License, all in COPYING. Support runs through the Stack Overflow jq tag, Discord and the wiki. Plain sed, awk and grep remain the alternative for line oriented text, while jq owns input that must parse as JSON structure.

Editorial conclusion

Choose jq when shell pipelines must slice, filter, map or transform JSON without adding a runtime, and Docker or a static binary fits distribution. Skip it when the team needs an interactive JSON browser or a library embedded in another language. Before standardizing, confirm which of the three install paths matches the fleet and verify the MIT and CC BY 3.0 grants in COPYING against the deployment policy.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes