Install & Compatibility
Where this runs
tested against v4.0.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.95 runs
installs and imports cleanly · install 0.0s · import 0.096s · 18.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.088s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
open
✓ from jsonlines import open
The primary convenience function for reading/writing files.
Reader
✓ from jsonlines import Reader
For explicit control over reading from file-like objects.
Writer
✓ from jsonlines import Writer
For explicit control over writing to file-like objects.
The quickstart demonstrates writing and reading JSON Lines data using `jsonlines.open()` for file paths and the `jsonlines.Writer`/`jsonlines.Reader` classes for file-like objects (like `io.StringIO`). It covers basic object serialization, deserialization, and the use of context managers for proper resource handling.
import jsonlines
import io
import os
# Create a dummy file for demonstration
output_file = "example_data.jsonl"
data_to_write = [
{"id": 1, "name": "Alice", "email": "alice@example.com"},
{"id": 2, "name": "Bob", "email": "bob@example.com", "status": "active"},
{"id": 3, "name": "Charlie", "data": {"city": "New York", "zip": "10001"}}
]
# Writing JSON Lines data using the convenience 'open' function
with jsonlines.open(output_file, mode='w') as writer:
writer.write_all(data_to_write)
print(f"Wrote {len(data_to_write)} records to {output_file}")
# Reading JSON Lines data
print("\nReading records:")
read_records = []
with jsonlines.open(output_file) as reader:
for obj in reader:
read_records.append(obj)
print(obj)
print(f"Total records read: {len(read_records)}")
assert read_records == data_to_write
# Example of writing to an in-memory buffer using Writer class
buffer = io.StringIO()
with jsonlines.Writer(buffer) as writer:
writer.write({"log_event": "started", "timestamp": "2023-01-01T12:00:00Z"})
writer.write({"log_event": "processed", "item_id": 123})
buffer.seek(0) # Reset buffer position to read
print("\nReading from in-memory buffer:")
with jsonlines.Reader(buffer) as reader:
for log_entry in reader:
print(log_entry)
# Clean up the dummy file
os.remove(output_file)
print(f"\nCleaned up {output_file}")
Debug
Known issues
gotchaAlways use `jsonlines.open()`, `jsonlines.Reader`, or `jsonlines.Writer` within a `with` statement (as a context manager) or ensure `.close()` is called manually. Failing to do so can lead to unwritten data or unreleased file handles.fixWrap file operations with `with jsonlines.open(...) as reader/writer:` or `with jsonlines.Reader(...) as reader:` etc.
affects: All
gotchaThe `jsonlines` format expects one complete JSON object per line, delimited by a newline character. It is NOT a single large JSON array. Attempting to parse a traditional JSON array file with `jsonlines` will likely fail or yield incorrect results.fixEnsure your input data strictly adheres to the 'one JSON object per line' format. If you have a JSON array, you must serialize each element to a new line manually before using `jsonlines`.
affects: All
gotchaWhen providing a custom `dumps` callable to `jsonlines.Writer`, the `compact` and `sort_keys` arguments will be ignored. The custom callable takes precedence over these built-in formatting options.fixIf using a custom `dumps` function, implement any desired compaction or key sorting logic within that function.
affects: All
gotchaWhile Python's file I/O often handles various newline characters, the `jsonlines` specification primarily uses `\n`. For maximum compatibility when *generating* `jsonlines` files that might be consumed by other tools, it's best to ensure consistent `\n` line endings. The library handles standard-compliant line breaking.fixRely on the library's default line breaking for writing, which is compliant. Be aware that consuming external files might involve universal newline handling.
affects: All
breakingSome external command-line tools (e.g., DuckDB CLI v1.5.0) have changed their `--jsonlines` flag behavior or removed it, opting instead for `--json` which outputs a single JSON array (not JSONL). This can silently break ETL pipelines that expect newline-delimited JSON. This is a common point of confusion in the ecosystem, not a direct breaking change in this `jsonlines` Python library, but relevant to its users.fixAlways verify the output format of external tools. If a tool changes its JSONL output behavior, adapt your data ingestion process accordingly (e.g., convert a JSON array to JSONL or use `jsonlines` to read correctly formatted output).
affects: N/A (external tools)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jsonlines'
The 'jsonlines' library has not been installed in your Python environment.
fixRun `pip install jsonlines` in your terminal or command prompt to install the library.
jsonlines.jsonlines.InvalidLineError: line contains invalid json
A line in your JSON Lines file is not a properly formatted JSON object, or it contains data that does not conform to an expected type if validation is enabled.
fixEnsure each line in your `.jsonl` file is a complete, self-contained, and valid JSON object. If you need to skip invalid lines during reading, you can pass `skip_invalid=True` to the reader, e.g., `for obj in reader.iter(skip_invalid=True):`
AttributeError: 'Reader' object has no attribute 'tell'
`jsonlines.Reader` and `jsonlines.Writer` objects are wrappers that provide specific methods for JSON Lines processing, and they do not expose all methods of the underlying file-like object directly.
fixInstead of attempting to use raw file methods like `tell()` or `seek()` directly on the `jsonlines.Reader`/`Writer` instance, use the methods provided by the `jsonlines` library, such as iterating directly over the `Reader` for lines or using `reader.read()`.
Attempting to write to a file using `jsonlines.open()` overwrites existing content instead of appending.
The default mode for `jsonlines.open()` might be 'w' (write), or 'w' was explicitly used, which truncates the file if it exists before writing.
fixSpecify `mode='a'` (append) when opening the file with `jsonlines.open()` to add new JSON objects to the end of an existing file. Example: `with jsonlines.open('output.jsonl', mode='a') as writer: writer.write(data)` Upgrade
Version history
4.0.0latest on PyPI · released Sep 1, 2023
Audit
Dependencies
No dependency data recorded yet.