Ijson is an iterative JSON parser for Python that provides standard iterator interfaces. It enables efficient processing of large JSON data streams without loading the entire document into memory, making it ideal for handling massive JSON files, streaming APIs, and memory-constrained environments. The library is currently at version 3.5.0 and maintains an active release cadence with regular updates and binary wheel support for major platforms.
Install & Compatibility
Where this runs
tested against v3.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.975 runs
installs and imports cleanly · install 0.0s · import 0.034s · 18.3MB
glibcpy 3.10–3.975 runs
installs and imports cleanly · install 1.6s · import 0.030s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ijson
✓ import ijson
✗ import ijson # (implicitly uses slower Python backend if no C backend is available or configured)
While `import ijson` is correct, for performance-critical applications, it's often better to explicitly import a faster C-based backend if available, as the default might fall back to the pure Python parser.
items
✓ from ijson import items
The `items` function is a high-level interface for extracting Python objects from a JSON stream under a specified prefix.
parse
✓ from ijson import parse
The `parse` function provides a lower-level event-driven interface, yielding (prefix, event, value) tuples.
yajl2_cffi
✓ import ijson.backends.yajl2_cffi as ijson
Explicitly imports the `yajl2_cffi` backend for optimal performance, aliasing it as `ijson` for consistent API usage.
This quickstart demonstrates how to use `ijson.items` to iteratively parse JSON data, extracting Python objects from specified paths. It also shows how to explicitly select a backend for improved performance. `ijson` expects file-like objects opened in binary mode (`'rb'`). The path syntax uses `.` for object keys and `.item` for elements within arrays.
import ijson
import os
from io import BytesIO
# Example JSON data (simulating a file-like object)
json_data = b'{"earth": {"europe": [{"name": "Paris", "type": "city"}, {"name": "Rome", "type": "city"}]}, "america": [{"name": "New York", "type": "city"}]}'
# For demonstration, you might use BytesIO or a real file opened in binary mode
with BytesIO(json_data) as f:
# Using the 'items' function to extract objects under a specific path
# 'earth.europe.item' means: 'earth' object, then 'europe' array, then each 'item' in the array
print("European cities:")
for city in ijson.items(f, 'earth.europe.item'):
print(city)
# Reset stream for another parse, or open a new file
with BytesIO(json_data) as f:
print("\nAll cities:")
# Using 'item' for a top-level array or '.item' for nested array items without specific object keys
# Or a more general path if structure is less strict
for city_or_state in ijson.items(f, 'earth..item'): # Matches any item within 'earth' object (e.g., europe.item, america.item)
if isinstance(city_or_state, dict) and city_or_state.get('type') == 'city':
print(city_or_state)
# Example with explicit backend selection (recommended for production)
# Ensure 'ijson[yajl2_cffi]' is installed for this to be effective
try:
import ijson.backends.yajl2_cffi as ijson_fast
with BytesIO(json_data) as f:
print("\nEuropean cities (with yajl2_cffi backend):")
for city in ijson_fast.items(f, 'earth.europe.item'):
print(city)
except ImportError:
print("\n'yajl2_cffi' backend not available. Install with 'pip install ijson[yajl2_cffi]'.")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ijson'
The 'ijson' package is not installed in your Python environment or the Python interpreter being used does not have access to the installed package.
fixInstall the package using pip: `pip install ijson`
ijson.common.IncompleteJSONError: parse error: trailing garbage
This error occurs when the input JSON stream contains multiple top-level JSON objects or values, which is not standard JSON but is common in JSON line-delimited streams or concatenated JSON documents.
fixPass the `multiple_values=True` option to the ijson parsing function you are using (e.g., `ijson.items(f, 'prefix', multiple_values=True)`).
ijson.common.IncompleteJSONError: lexical error: invalid char in json text
This typically indicates that the input data is not valid JSON, contains invalid characters (e.g., non-UTF-8 bytes), or includes non-standard JSON values like `NaN`.
fixEnsure your input data is strictly valid JSON and properly UTF-8 encoded. If the data is not truly UTF-8, consider pre-processing it with `iconv -f utf8 -t utf8 -c` or similar tools to correct invalid byte sequences, or use an `errors='ignore'` or `errors='replace'` strategy when decoding bytes to strings if reading as text.
YAJL shared object not found
The ijson library, particularly its faster backends (`yajl2_c`, `yajl2_cffi`, `yajl2`), relies on the YAJL C library, which is not found or correctly linked on your system.
fixInstall the YAJL development libraries (e.g., `sudo apt-get install libyajl-dev` on Debian/Ubuntu, `brew install yajl` on macOS) and then reinstall `ijson`. Alternatively, you can explicitly use the pure Python backend by importing `ijson.backends.python as ijson`.
TypeError: can't concat bytes to str
This error arises when you mix byte-string (binary) and regular string (text) data during file processing or when `ijson` expects binary input but receives text, or vice-versa, often due to how the input file is opened.
fixOpen your JSON file in binary read mode (`'rb'`) if feeding it directly to `ijson` functions, as `ijson` prefers binary input. Example: `with open('data.json', 'rb') as f: ...`. Audit
Dependencies
yajloptionalUsed by the faster `yajl2_c` backend. Requires `libyajl-dev` on Debian/Ubuntu systems for compilation.
cffirequiredUsed by the `yajl2_cffi` backend, which offers C-level performance without direct C compilation.