Who jaq is for#
DevOps engineers running jq in CI pipelines
jaq drops in as a faster binary for teams that process JSON API responses, transform config files, or parse log output in CI scripts. Because filter syntax is compatible with jq, the switch requires changing only the binary name, not the script logic.
Skip if:
If your CI scripts use jq's `$ENV` object or `debug` format, jaq does not implement those yet. Verify filter compatibility before switching.
Rust developers embedding a jq interpreter
jaq-core is a Rust library for compiling and running jq programs programmatically. It is safe for multi-threaded use and supports custom data types through the ValT trait. Amazon's ion-cli project integrated it for jq support, noting that the ValT trait made adding custom type support straightforward.
Skip if:
If you need a C FFI to the original jq C library for interoperability with non-Rust code, the original jq project provides that path.
Data engineers processing mixed-format config files
Teams working with JSON, YAML, TOML, and CBOR configurations can use jaq as a single query tool across all formats. This is useful for Kubernetes config auditing, Helm chart inspection, or any pipeline where source files use different serialization formats.
Skip if:
If your input is JSON only and you are satisfied with jq's speed for interactive use, the practical difference is small. jaq's benefit is most visible at scale with thousands of files per run.
Developers processing high-volume small-file JSON
One community user reported that a Rust program using jaq executed all queries over all files three times while a Python and jq equivalent was still on its first pass. The startup overhead reduction is most pronounced when the processor is invoked thousands of times rather than once on a large file.
Skip if:
For single large-file processing rather than many small files, the startup advantage is irrelevant. Benchmark the specific operation to confirm whether jaq helps your use case.
The problem it solves#
jq is the default tool for JSON processing in shell pipelines, but it carries two friction points that compound in production pipelines. First, startup time: jq 1.6 added roughly 50 milliseconds per invocation, and scripts that process thousands of small files turn that overhead into seconds of cumulative latency. jq 1.7 improved startup considerably, but jaq still beats it across most benchmark categories. Second, predictability: jq has documented edge cases where its output diverges from the implied filter semantics. Debugging those edge cases in a long pipeline is slow and unreliable. Developers working with JSON data at scale need a processor they can trust to produce consistent output and start fast enough not to be the bottleneck in a scripted loop.
How it solves it#
Drop-in jq replacement
jaq accepts jq filter syntax and can replace the jq binary directly in shell scripts and pipelines. Most existing jq filters run without modification. Known compatibility differences are documented; jaq does not implement jq's `$ENV` object or `debug` output format, so pipelines using those features need adjustments.
YAML, CBOR, TOML, and XML support
Where jq only processes JSON, jaq reads YAML, CBOR, TOML, and XML as input using the same query filters. This removes conversion steps from pipelines that mix data formats, letting a single tool handle heterogeneous config files and API payloads.
Faster on most benchmark operations
jaq-3.0 is fastest among jq-1.8.1, gojq-0.12.18, and jaq-3.0 on 20 of 29 benchmark categories, including group-by (260ms vs 1790ms for jq), tree-contains (90ms vs 830ms), and reverse (30ms vs 440ms). Benchmarks were run on an AMD Ryzen 5 5500U using the project's bench.sh script.
Embeddable Rust library (jaq-core)
Beyond the CLI, jaq ships as jaq-core, a Rust crate that compiles and runs jq programs inside Rust applications. Unlike the jq C API, jaq-core is safe for multi-threaded environments and supports arbitrary data types through the ValT trait, allowing it to operate on custom Rust types.
Security-audited core
jaq's core has been reviewed twice by Radically Open Security under NLnet NGI grants. Both audits found only moderate or low severity issues, all of which were addressed. The codebase includes more than 500 tests and multiple fuzzing targets at jaq-core/fuzz.
Strengths and trade-offs#
Strengths
- Correctness as a stated design goaljaq explicitly prioritizes correct filter semantics over backward compatibility where jq's behavior is ambiguous. For production pipelines where a JSON processing edge case could silently corrupt output, this distinction matters versus jq's historical behavior.
- Memory safety from Rustjaq is written in Rust, which prevents memory corruption and undefined behavior from parser errors. The security audit confirms it does not allow input data or filters to initiate I/O operations except reading files before execution, making it safer to run on untrusted input than alternatives written in C.
- Zero-dependency single binaryThe jaq binary is statically linked and installs via Homebrew or Cargo. Replacing jq on a server means copying one file. There is no runtime, no interpreter, and no configuration required to start processing JSON.
- Funded and independently auditedjaq received two NLnet NGI grants that funded both development and independent security audits by Radically Open Security. This distinguishes it from most hobbyist CLI tools and signals sustained investment in correctness and security over time.
Trade-offs
- -Incomplete jq compatibilityjaq does not implement all of jq's functionality. Notably absent are jq's `$ENV` object (for reading environment variables in filters) and the `debug` output format. Users migrating from jq need to verify their specific filter set against jaq's documented compatibility before switching production pipelines.
- -No resource exhaustion protectionjaq explicitly does not guard against runaway memory or CPU consumption from deeply recursive filters. A filter like `jaq -n 'def f: 1+f; f'` causes a stack overflow with no countermeasure. This makes jaq unsuitable for running untrusted user-supplied filters without an external sandbox or resource limits.
jaq vs alternatives#
jaq vs jq
Both tools process JSON from the command line using the same filter syntax. jq is the original, written in C, and remains the default in most Linux package managers. jaq is a Rust reimplementation focused on correctness and performance.
| Feature | jaq | jq |
|---|---|---|
| License | MIT | MIT |
| Language | Rust | C |
| Self-hosting | Single binary | Single binary |
| Multi-format input | JSON, YAML, CBOR, TOML, XML | JSON only |
| Benchmark wins | 20 of 29 vs jq-1.8.1 | 5 of 29 vs jaq-3.0 |
| Security audits | Two (NLnet grants) | None published |
$ENV support | No | Yes |
jaq-3.0 outperforms jq-1.8.1 on 20 of 29 benchmark operations, including group-by (260ms vs 1790ms), tree-contains (90ms vs 830ms), and sort (90ms vs 430ms). jq is faster on a handful including reduce (700ms vs 740ms) and pyramid (250ms vs 300ms). For most pipeline uses, jaq is a faster drop-in; the gap is most pronounced when the processor runs thousands of times rather than once on a large file.
jaq is the better choice when correctness of edge-case filter semantics matters, when you need YAML, TOML, or CBOR support without a separate conversion step, or when startup time is a bottleneck in your pipeline. jq is still the better fit when you depend on $ENV or debug output, or when you need the C API for interoperability with non-Rust applications.
jaq vs Commercial Data Processing Tools
For developers who process JSON data in scripts, the comparison to commercial tools is primarily about fit-for-purpose. Paid log analysis services like Splunk charge per volume and require infrastructure setup for batch JSON transformation tasks that jaq handles in a single invocation with no cost. jaq's fit is narrow: structured data transformation in shell pipelines and scripts, not interactive dashboards or alerting workflows. Teams replacing ad hoc jq usage in CI pipelines or log processing scripts will find jaq a capable drop-in; teams needing observability or search features should look at purpose-built tools instead.
Quick start#
Install jaq using Homebrew on macOS and Linux, or via Cargo for a source build.
```bash
brew install jaq
cargo install --locked jaq
```What it's built on#
- Languages
- JavaScriptRust
FAQ#
Is jaq compatible with existing jq filters?
In most cases, yes. jaq runs the majority of jq filters without modification. Known differences include the absence of jq's $ENV object and the debug output format. Test your specific filters against jaq before replacing jq in production pipelines.
How do I install jaq?
On macOS or Linux, the quickest path is brew install jaq. Install from source with cargo install --locked jaq if you have Rust's Cargo toolchain. Pre-built binaries for Linux, macOS, and Windows are also available on the GitHub releases page.
Is jaq safe to run on untrusted input?
jaq guarantees it will not corrupt memory and will not allow filters to initiate I/O operations on untrusted data. It does not, however, protect against resource exhaustion: deeply recursive filters can cause stack overflows or unbounded memory use. For running untrusted user-supplied filters, apply external resource limits such as ulimit or container CPU and memory caps.
How does jaq compare to gojq?
jaq-3.0 is faster than gojq-0.12.18 on 20 of 29 benchmarks. gojq is faster on tree-flatten because it implements that filter natively. Both are MIT licensed. gojq is written in Go and is often cited as a reference for jq compatibility; jaq prioritizes correctness and Rust-ecosystem integration.
Can I use jaq as a library in my Rust project?
Yes. The jaq-core crate on crates.io provides an API for compiling and running jq programs from Rust. It is thread-safe, unlike the C jq API, and supports custom data types through the ValT trait. Amazon's ion-cli project uses it to process Amazon Ion data with jq-style filters.
Similar open-source tools#
jnv
Interactive jq filter editor with live JSON navigation
flowsint
Self-hosted graph tool for OSINT and cybersecurity investigations
FckSignups
Open-source tools that work instantly, no signup required
Automated-AI-Web-Researcher-Ollama
Ollama-powered web researcher that breaks queries into focus areas
pdf-inspector
Rust-powered PDF parser with smart OCR routing for AI pipelines
crawl4ai
LLM-ready web crawling without API keys or rate limits