# How jq's --stream Works: Inside the Streaming JSON Parser

> Learn how jq's --stream option enables incremental parsing of massive JSON documents without loading them into memory. Discover how it emits [path, value] pairs as leaf values are found.

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

---

**The `--stream` option activates incremental parsing that emits `[path, value]` pairs immediately as leaf values are discovered, enabling jq to process massive JSON documents without loading them entirely into memory.**

By default, jq parses complete JSON documents into memory before applying filters. The **`--stream`** option fundamentally changes this behavior, engaging a specialized parser implementation in [`src/jv_parse.c`](https://github.com/jqlang/jq/blob/main/src/jv_parse.c) that tracks location via a dynamic path array and yields values piecemeal. This mode, controlled by the `JV_PARSE_STREAMING` flag set in [`src/main.c`](https://github.com/jqlang/jq/blob/main/src/main.c), allows pipelines to begin