{"library":"jsonlines","title":"jsonlines Python Library","description":"jsonlines is an active Python library (version 4.0.0) that provides helpers for working with the JSON Lines (also known as NDJSON) text file format. It simplifies reading and writing streams of newline-delimited JSON objects, offering features like transparent handling of string and byte streams, support for optional faster JSON parsers (like `orjson` and `ujson`), built-in data validation, and robust error handling. Its design prevents common pitfalls and ensures standard-compliant line breaking.","status":"active","version":"4.0.0","language":"en","source_language":"en","source_url":"https://github.com/wbolster/jsonlines","tags":["json","jsonlines","ndjson","serialization","deserialization","streaming","file-format"],"install":[{"cmd":"pip install jsonlines","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The primary convenience function for reading/writing files.","symbol":"open","correct":"from jsonlines import open"},{"note":"For explicit control over reading from file-like objects.","symbol":"Reader","correct":"from jsonlines import Reader"},{"note":"For explicit control over writing to file-like objects.","symbol":"Writer","correct":"from jsonlines import Writer"}],"quickstart":{"code":"import jsonlines\nimport io\nimport os\n\n# Create a dummy file for demonstration\noutput_file = \"example_data.jsonl\"\ndata_to_write = [\n    {\"id\": 1, \"name\": \"Alice\", \"email\": \"alice@example.com\"},\n    {\"id\": 2, \"name\": \"Bob\", \"email\": \"bob@example.com\", \"status\": \"active\"},\n    {\"id\": 3, \"name\": \"Charlie\", \"data\": {\"city\": \"New York\", \"zip\": \"10001\"}}\n]\n\n# Writing JSON Lines data using the convenience 'open' function\nwith jsonlines.open(output_file, mode='w') as writer:\n    writer.write_all(data_to_write)\nprint(f\"Wrote {len(data_to_write)} records to {output_file}\")\n\n# Reading JSON Lines data\nprint(\"\\nReading records:\")\nread_records = []\nwith jsonlines.open(output_file) as reader:\n    for obj in reader:\n        read_records.append(obj)\n        print(obj)\n\nprint(f\"Total records read: {len(read_records)}\")\nassert read_records == data_to_write\n\n# Example of writing to an in-memory buffer using Writer class\nbuffer = io.StringIO()\nwith jsonlines.Writer(buffer) as writer:\n    writer.write({\"log_event\": \"started\", \"timestamp\": \"2023-01-01T12:00:00Z\"})\n    writer.write({\"log_event\": \"processed\", \"item_id\": 123})\n\nbuffer.seek(0) # Reset buffer position to read\nprint(\"\\nReading from in-memory buffer:\")\nwith jsonlines.Reader(buffer) as reader:\n    for log_entry in reader:\n        print(log_entry)\n\n# Clean up the dummy file\nos.remove(output_file)\nprint(f\"\\nCleaned up {output_file}\")","lang":"python","description":"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."},"warnings":[{"fix":"Wrap file operations with `with jsonlines.open(...) as reader/writer:` or `with jsonlines.Reader(...) as reader:` etc.","message":"Always 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure 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`.","message":"The `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.","severity":"gotcha","affected_versions":"All"},{"fix":"If using a custom `dumps` function, implement any desired compaction or key sorting logic within that function.","message":"When 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Rely on the library's default line breaking for writing, which is compliant. Be aware that consuming external files might involve universal newline handling.","message":"While 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Always 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).","message":"Some 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.","severity":"breaking","affected_versions":"N/A (external tools)"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}