# When to Use jq's --stream Option for Large JSON Processing

> Learn when to use jq --stream for large JSON processing. Efficiently handle massive files and stream data without loading entire structures into memory.

- Repository: [jqlang/jq](https://github.com/jqlang/jq)
- Tags: best-practices
- Published: 2026-04-11

---

**Use `jq --stream` when processing JSON files too large to fit in memory, when extracting specific values from massive documents without loading the entire structure, or when handling line-delimited JSON streams incrementally.**

The `jq` command-line JSON processor normally materializes the entire input document into an in-memory tree before applying filters. According to the [jqlang/jq](https://github.com/jqlang/jq) source code, the `--stream` flag switches the parser into incremental mode, yielding path-value pairs that enable O(depth) memory usage rather than O(size).