fq: jq's Query Language Applied to Binary File Formats

What fq Solves and Who It Is For

Binary files have historically required format-specific tools: tshark for packet captures, ffprobe for media, readelf for ELF binaries. fq takes a different approach. It applies jq's expression language uniformly across binary formats, so a developer who already knows how to filter and transform JSON with jq can immediately start querying binary files without learning a new query model. The tool covers network captures, media containers, certificate formats, archive files, database storage files, and serialization formats in a single binary. According to the README, fq is a tool, language, and decoder set for working with binary formats and data. It behaves and feels similar to jq in most cases, uses the same expression language, and adds a structural hex viewer, nested format decoding, slicing and concatenating binary data, bit-level decoding, and an interactive REPL with auto-completion.

Installing fq Across Platforms

fq publishes pre-built binaries for macOS, Linux, and Windows on its GitHub releases page. On macOS, the easiest installation path uses the custom Homebrew tap.

brew install wader/tap/fq

On macOS, if you download the binary directly instead of using a package manager, you may need to allow it to run by going into Security preferences after the initial blocked launch attempt. The README also documents the quarantine removal commands for this case.

On Windows, fq is available via Scoop. On Arch Linux, it is in the extra repository under pacman. For Nix and Guix users, it is available in those package collections. To build from source, Go 1.22 or later is required.

go install github.com/wader/fq@latest

This installs the latest release. Using @master installs from the current development branch. The Dockerfile in the repository also provides a build target for containerized use.

Basic Usage: Dot, Decode, and the Hex Viewer

The README describes the basic invocation as three forms: `fq . file`, `fq d file`, or `fq 'some query' file`. The dot expression displays the decoded structure of the file, similar to how jq's dot expression pretty-prints JSON. The d expression shows a hex dump with structural annotations. Both commands automatically detect the file format from the binary content.

For more specific queries, you compose jq expressions that navigate the decoded structure. The same dot-notation path syntax you use with JSON works on binary-decoded structures. The interactive REPL, launched by running fq without arguments or with a file, provides auto-completion for format fields, which helps when exploring an unfamiliar binary format without knowing its schema in advance.

For formats like XML, YAML, and TOML, fq can transform both from and to jq values. This means it works as a converter between binary and structured text representations for supported serialization formats.

Format Coverage: 170 Formats Across Media, Network, and Archives

The README lists over 170 supported formats. Media formats include MP3, MP4, FLAC, OGG, WAV, AIFF, HEIF, JPEG, PNG, GIF, and WebP, along with codec-level decoders for H.264 (AVC), H.265 (HEVC), VP8, VP9, AV1, and Opus. Network formats include DNS, PCAP, PCAPNG, IPv4, IPv6, TCP, UDP, TLS, ICMP, and several Ethernet frame types. Binary executable formats include ELF, Mach-O, and WebAssembly. Archive formats include ZIP, TAR, BZIP2, and GZIP. Serialization formats include BSON, CBOR, MessagePack, Protobuf, and Avro OCF. Bit-oriented formats include level-specific decoders for AVC SPS, PPS, and SEI units. The go.mod file names gojq, a forked version of the gojq project by itchyny, as fq's underlying expression engine. This fork adds the binary-specific extensions to the jq language that fq requires. The PostgreSQL btree, heap, and control file decoders make fq useful for low-level database forensics, which is not a use case most binary tools cover.

Limitations and Cases Where fq Is Not the Right Tool

fq does not write binary files. It is a read-only inspection and query tool. If you need to modify a binary file or generate one from scratch, you need a different tool. Its expression language is jq's, which is powerful but has a steep learning curve for those unfamiliar with functional-style filtering. For formats not in fq's list, there is no fallback decoding; the tool either falls back to treating the file as raw bytes or returns an error, depending on the context. The README notes that fq uses a fork of gojq rather than the standard jq implementation, so there may be subtle differences in edge cases. The manual is at wader.github.io/fq and also available as a man page, but the README itself is sparse on advanced query examples. Complex queries require reading the manual or the jq documentation.

fq versus Wireshark, kaitai, and Hex Editors

Wireshark is the standard tool for network traffic analysis. It provides a GUI, protocol dissectors, and filtering for live captures. fq does not capture live traffic; it reads existing capture files. tshark -T json is a common way to export Wireshark data for scripting, and fq addresses a similar need but applies the same interface to non-network formats as well. kaitai is a declarative binary format parsing system where you write a format schema in YAML and generate parsers for multiple languages. fq does not require schema files; its decoders are compiled in. ImHex, listed in the README as a related project, is a GUI hex editor for reverse engineers. fq is a CLI tool. The README mentions HexFiend for macOS as an inspiration and also lists binspector, which has a query language and REPL, as a related prior work. The key difference between fq and these tools is the jq expression language: if a developer's existing workflow uses jq, fq extends that investment to binary data.

Maintenance and Licence

The last push to the repository was on 2026-09-27, one day before this article. Recent releases include v0.18.0 on 2026-08-25 and v0.17.0 on 2026-03-15, with the go.mod file tracking Go 1.26 and the Dockerfile referencing Go 1.27.1. The Makefile in the repository includes a `Bumpfile` mechanism and automated dependency update comments in go.mod, suggesting a structured dependency maintenance process. The repository is hosted at github.com/wader/fq. The README credits the gojq implementation by itchyny as a foundational dependency and HexFiend and the jq language by stedolan as inspirations. The licence is not specified in the prompt; the repository has a LICENSE file at the root, and the README includes no explicit licence statement in the text provided.

Editorial conclusion

fq is the right tool for developers and reverse engineers who already know jq and want to inspect, query, or slice binary files without writing a custom parser. It is not the right choice when you need a GUI, a declarative schema format, or when your format is not in its list. Before committing to it, run fq --version to confirm the release matches your needs, and check the supported formats list against the specific formats you work with.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. wader/fq on GitHub