How to Install and Use fq in Linux for Inspecting and Parsing Binary File Formats

Working with binary files such as multimedia containers, compiled executables, network packet captures, and image metadata often requires multiple disparate CLI utilities. The fq tool bridges this gap by functioning as a jq clone specifically designed for binary file formats. It decodes raw byte streams into structured, queryable data trees, allowing engineers and system administrators to inspect nested metadata, extract sub-streams, and manipulate binary representations effortlessly.

What Is fq and Why Use It Over Traditional Hex Dumpers?

Traditional tools like hexdump, xxd, or strings display linear byte sequences without semantic awareness of the underlying file format. In contrast, fq parses the internal specification of over one hundred binary formats—including MP4, FLAC, ZIP, ELF, Tar, WebP, and PCAP—transforming raw chunks into interactive objects.

Because fq uses the exact same expression syntax as jq, you can filter headers, extract audio track sample rates, inspect ELF symbol tables, and query protocol flags using familiar pipeline operators and conditionals.

Installing fq Across Major Linux Distributions

You can install fq quickly through distribution package managers, pre-compiled GitHub release archives, or Go build tooling.

Installing on Arch Linux

On Arch Linux and derivatives, fq is directly available in the official extra repository:

sudo pacman -S fq

Installing on Ubuntu and Debian

For Debian and Ubuntu environments, downloading the standalone static binary from GitHub releases ensures you obtain the latest format decoders:

FQ_VERSION=$(curl -s https://api.github.com/repos/wader/fq/releases/latest | grep '"tag_name":' | sed -E 's/.*"v([^"]+)".*/\1/')
curl -LO "https://github.com/wader/fq/releases/download/v${FQ_VERSION}/fq_${FQ_VERSION}_linux_amd64.tar.gz"
tar -xzf "fq_${FQ_VERSION}_linux_amd64.tar.gz"
sudo install -m 755 fq /usr/local/bin/
rm -f "fq_${FQ_VERSION}_linux_amd64.tar.gz" fq

Installing via Go

If Go is installed on your Linux workstation, install fq directly to your Go path:

go install github.com/wader/fq@latest

Inspecting and Decoding Binary Files Interactively

When run without arguments, fq opens an interactive Read-Eval-Print Loop (REPL) equipped with syntax highlighting, autocomplete, and visual hex dumps.

To inspect an MP4 video container in interactive mode:

fq video.mp4

Inside the interactive prompt, typing a period (.) displays the top-level atom hierarchy (such as ftyp, moov, and mdat). Navigating nested structures is as simple as accessing object properties:

.moov.mvhd

Running Command-Line Queries and Filtering Data

For automated workflows and shell scripts, fq accepts expressions directly from the command line, emitting standard JSON or formatted text outputs.

Extracting Audio Codec Details from an MP4 File

Query specific track properties by filtering through track header structures:

fq -d mp4 '.moov.trak[] | select(.mdia.hdlr.handler_type == "soun") | .mdia.minf.stbl.stsd.entries[0].format' video.mp4

Inspecting ELF Binary Headers and Architectures

To verify the target architecture and entry point of a compiled Linux binary:

fq -d elf '{arch: .header.e_machine, entry: .header.e_entry}' /bin/ls

Analysing Network Capture (PCAP) Headers

To view packet lengths and protocols stored in a PCAP capture file:

fq -d pcap '.packets[:5] | .[].header' capture.pcap

Converting Binary Payloads into Clean JSON

To integrate binary inspection into downstream Python or Node.js processing scripts, pass the -o json option to convert decoded structures into clean JSON streams:

fq -d mp3 -o json '.frames[] | select(.id == "TIT2")' song.mp3 > id3_tags.json

This allows rapid parsing of complex binary data without requiring custom binary unpackers or specialised C libraries.