How to Install and Use fq in Linux to Parse, Inspect, and Query Binary Formats

Working with binary files such as executable binaries (ELF, Mach-O), compressed archives (ZIP, tar, gzip), media containers (MP4, MP3, FLAC, JPEG, PNG), and network packet dumps often requires juggling cumbersome hex editors or specialised single-format analyzers. fq revolutionises binary inspection by serving as a comprehensive tool and parser that brings the expressive querying syntax of jq to binary formats.

Written in Go, fq parses binary streams into structured, queryable abstract syntax trees. It allows developers, reverse engineers, and system administrators to inspect file headers, unpack nested streams, decode bit fields, and transform binary structures directly within the Linux terminal. In this guide, explore how to install, configure, and use fq to dissect binary files with precision.

Key Advantages of fq for Binary Inspection

Traditional tools like hexdump, xxd, or objdump display raw bytes with minimal structural comprehension. In contrast, fq natively understands hundreds of file formats:

Feature	Standard Hex Tools (e.g. hexdump, xxd)	Binary Query Engine (fq)
Format Comprehension	Raw offset bytes without semantic context	Deep structural decoding (ELF, MP4, JPEG, TLS, PCAP, etc.)
Query Language	Requires piping to external grep or awk	Full jq-compatible functional query syntax
Interactive Exploration	Static text output	Interactive REPL with auto-completion and bit slicing
Bit-Level Precision	Byte-aligned only	Sub-byte bit ranges and arbitrary bit alignments

Installing fq on Linux Distributions

Depending on your distribution and preference, install fq via official package managers, precompiled binaries, or Go.

Method 1: Installing Precompiled Binaries from GitHub Releases

For any modern x86_64 or ARM64 Linux system, downloading the precompiled release binary provides the fastest route:

# Download the latest Linux x86_64 release archive
curl -LO https://github.com/wader/fq/releases/latest/download/fq_linux_amd64.tar.gz

# Extract the archive
tar -xzf fq_linux_amd64.tar.gz

# Relocate the binary to your executable path
sudo mv fq /usr/local/bin/

# Verify permissions and executable status
sudo chmod +x /usr/local/bin/fq

# Confirm installation
fq --version

Method 2: Installing via Go

If you maintain a Go environment (version 1.21 or later) on your workstation, install directly from source:

go install github.com/wader/fq@latest

Ensure that ~/go/bin is included in your shell’s PATH variable.

Method 3: Installing on Arch Linux

Arch Linux packages fq in the community repositories:

sudo pacman -S fq

Core Syntax and First Steps with fq

The basic execution model of fq mirrors that of jq: provide an optional query expression followed by the target file path:

fq 'EXPRESSION' /path/to/binary/file

If you omit the expression and supply only a filename, fq automatically launches an interactive REPL session, allowing you to traverse fields interactively.

Practical Examples: Querying Common Binary Formats

The real power of fq emerges when extracting specific metadata values or embedded streams from complex multimedia and executable files.

1. Inspecting Linux ELF Executables

To inspect the header architecture and entry point of a compiled binary (e.g. /bin/ls):

# Display the primary ELF header
fq -d elf '.header' /bin/ls

# Extract the target architecture and entry point address
fq -d elf '{arch: .header.e_machine, entry: .header.e_entry}' /bin/ls

To list all shared libraries required by the binary:

fq -d elf '[.program_headers[] | select(.p_type == "interp") | .interp]' /bin/ls

2. Parsing Media Container Metadata (MP4 / QuickTime)

MP4 video files use nested hierarchical “boxes” (atoms) such as ftyp, moov, and trak. Extracting track details without heavy video editors is simple:

# Inspect all top-level boxes in an MP4 file
fq 'keys' sample_video.mp4

# Query video track resolution and duration
fq '.moov.mvhd | {timescale: .timescale, duration: .duration}' sample_video.mp4

3. Extracting EXIF Metadata from JPEG Images

Inspect raw image segments and camera calibration data without decoding pixel arrays:

# Query the EXIF segment of a photograph
fq -d jpeg '.segments[] | select(.marker == "app1") | .exif' photograph.jpg

4. Analysing Network Capture Files (PCAP)

To audit packet streams and protocols within network dump files:

# Count total captured packets
fq -d pcap '.packets | length' capture.pcap

# Extract source and destination IP addresses from TCP packets
fq -d pcap '[.packets[].packet.ip | {src: .src_ip, dst: .dst_ip}]' capture.pcap

Bit Slicing and Extracting Raw Embedded Payloads

In addition to rendering structured JSON descriptions of binary trees, fq can extract raw byte slices or re-encode nested compressed payloads directly to standard output.

Exporting an Embedded Sub-Stream to Disk

If an MP4 file contains an embedded AAC audio track or a JPEG contains an embedded thumbnail, pipe the binary buffer directly out using the to_bytes function:

# Dump an embedded binary atom directly into a standalone file
fq -o 'raw' '.moov.udta.meta.ilst.covr.data' input.mp4 > album_cover.jpg

Inspecting Byte Offsets with the Hex View Filter

To examine the exact hexadecimal layout of a specific internal struct rather than the entire 500 MB file:

# Pipe a selected field into the internal hexdump visualizer
fq '.header | d' binary_sample.bin

Configuring Aliases and Shell Integration

To streamline repetitive diagnostic queries, define custom functions in your ~/.bashrc or ~/.zshrc file:

# Quick ELF security and architecture inspector
elfinfo() {
  fq -d elf '{class: .header.e_ident.class, type: .header.e_type, machine: .header.e_machine}' "$1"
}

# Rapid MP4 box inspector
mp4boxes() {
  fq '[.tracks[]? | {id: .tkhd.track_id, handler: .mdia.hdlr.handler_type}]' "$1"
}

Reload your shell with source ~/.bashrc to deploy your new diagnostic helpers across your development environments.

Streamlining Binary Forensic Workflows

By blending the declarative query model of jq with a modular binary decoder, fq eliminates the friction of reverse-engineering unknown file signatures, verifying file integrity, and validating network payloads. Integrate fq into your system toolkit to inspect complex file architectures with unmatched speed and clarity.