---
id: json-stream
version: "2.5.1"
license: Copyright (c) 2020 Jamie Cockburn Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# json-stream — Streaming JSON encoder and decoder

License: permissive · Maintenance: active · Downloads: 1.2M/mo

## What it is and what it does

json-stream is a JSON parser and encoder that processes data incrementally rather than loading entire documents into memory. It provides two primary modes: transient mode for minimal memory footprint (data is discarded after reading), and persistent mode for full random access like the standard library's json module. The package supports streaming from files, URLs, and iterators, and can handle multiple JSON documents in a single stream or JSON mixed with other data.

The package includes a visitor-based interface for depth-first traversal, native code parsing speedups for common platforms via json-stream-rs-tokenizer, and a pure Python fallback. It is designed to reduce memory consumption and latency when processing large or continuously arriving JSON data, making it suitable for applications that cannot afford to buffer entire documents.

Use it for:

- Process large JSON files that exceed available memory by streaming them incrementally.
- Parse NDJSON (newline-delimited JSON) or JSON Lines formats from log files or APIs.
- Consume JSON data from HTTP responses without buffering the entire response body.
- Implement visitor-pattern callbacks to extract specific fields from deeply nested JSON structures.
- Mix transient and persistent parsing modes to balance memory usage and random access within a single document.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Streams JSON data from files, URLs, or iterators without loading the entire document into memory, offering both dict/list-like and visitor-based interfaces for parsing and encoding.

Yes. The package is actively maintained, has no known vulnerabilities, installs with low friction, and solves a real problem (memory-efficient JSON streaming) that the standard library does not address. It is production-stable and supports current Python versions. Install it if you regularly work with large JSON files, streaming APIs, or NDJSON formats.

## Install

pip install json-stream
uv add json-stream
poetry add json-stream

## Installing json-stream

Before you install: Low friction install with a single native runtime dependency (json-stream-rs-tokenizer). Actively maintained with recent commits and stable production status across Python 3.8–3.14.

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for both open-source and proprietary projects.

Quickstart:

import json_stream

# Transient mode (low memory):
with open('large.json') as f:
    data = json_stream.load(f)
    for item in data['results']:
        print(item)

# Persistent mode (full access):
with open('data.json') as f:
    data = json_stream.load(f, persistent=True)
    print(data['key'])  # random access

Verify before relying:

- Performance comparison to standard json.load() on typical file sizes and network streams.
- Behavior and error recovery when encountering truncated or malformed JSON mid-stream.
- Memory overhead of the json-stream-rs-tokenizer native extension vs. pure Python fallback.

## Package facts

- License: Copyright (c) 2020 Jamie Cockburn Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

streaming json parser, memory-efficient json parsing, json decoder iterator, large json file processing, json streaming encoder, incremental json parsing, json visitor pattern, streaming-io, json-parsing, memory-efficient

[View on SkillFed](https://skillfed.io/packages/json-stream) · [View on PyPI](https://pypi.org/project/json-stream/)