Getting Started with JSONL
A complete beginner-friendly tutorial to master JSON Lines format in 10 minutes. From your first JSONL file to production-ready code.
Tutorial Contents
Short on time? Learn JSONL in 5 minutes condenses this tutorial into a single hands-on page.
What is JSONL?
Regular JSON
[
{"name": "Alice", "age": 30},
{"name": "Bob", "age": 25},
{"name": "Charlie", "age": 35}
]One big array - must load everything into memory
JSONL Format
{"name": "Alice", "age": 30}
{"name": "Bob", "age": 25}
{"name": "Charlie", "age": 35}One JSON object per line - stream line by line
Key Concept: JSONL is simply JSON objects separated by newlines. Each line is a complete, valid JSON object. That's it!
Your First JSONL File
Step 1: Create a new file
Create a file named users.jsonl (or users.json - both extensions work!)
Step 2: Add your data
Type or paste this content:
{"id": 1, "name": "Alice Johnson", "email": "[email protected]", "role": "developer"}
{"id": 2, "name": "Bob Smith", "email": "[email protected]", "role": "designer"}
{"id": 3, "name": "Charlie Brown", "email": "[email protected]", "role": "manager"}Congratulations!
You just created your first JSONL file! Each line is a complete JSON object representing one user.
Reading JSONL Files
Python
Method 1: Standard Library (Recommended)
import json
# Read line by line - memory efficient!
with open('users.jsonl', 'r') as file:
for line in file:
user = json.loads(line)
print(f"Name: {user['name']}, Role: {user['role']}")
# Output:
# Name: Alice Johnson, Role: developer
# Name: Bob Smith, Role: designer
# Name: Charlie Brown, Role: managerMethod 2: Load All Data
import json
# Read all at once (use only for small files)
users = []
with open('users.jsonl', 'r') as file:
for line in file:
users.append(json.loads(line))
print(f"Total users: {len(users)}") # Total users: 3JavaScript (Node.js)
Using readline module
const fs = require('fs');
const readline = require('readline');
async function readJSONL(filename) {
const fileStream = fs.createReadStream(filename);
const rl = readline.createInterface({
input: fileStream,
crlfDelay: Infinity
});
for await (const line of rl) {
const user = JSON.parse(line);
console.log(`Name: ${user.name}, Role: ${user.role}`);
}
}
readJSONL('users.jsonl');Go
Using bufio.Scanner
package main
import (
"bufio"
"encoding/json"
"fmt"
"os"
)
type User struct {
ID int `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
Role string `json:"role"`
}
func main() {
file, _ := os.Open("users.jsonl")
defer file.Close()
scanner := bufio.NewScanner(file)
for scanner.Scan() {
var user User
json.Unmarshal(scanner.Bytes(), &user)
fmt.Printf("Name: %s, Role: %s\n", user.Name, user.Role)
}
}Kept short to show the shape. Two things to add before this reads real data: bufio.Scanner refuses any line longer than 64KB and then stops quietly, so call scanner.Buffer to raise the limit and check scanner.Err() after the loop. The examples page shows the hardened version.
Writing JSONL Files
Python
import json
users = [
{"id": 1, "name": "Alice Johnson", "role": "developer"},
{"id": 2, "name": "Bob Smith", "role": "designer"},
{"id": 3, "name": "Charlie Brown", "role": "manager"}
]
# Write to JSONL file
with open('output.jsonl', 'w') as file:
for user in users:
# Write each object as JSON on its own line
file.write(json.dumps(user) + '\n')
print("File written successfully!")Important!
Always add \n after each JSON object. Don't forget the newline!
JavaScript (Node.js)
const fs = require('fs');
const users = [
{id: 1, name: "Alice Johnson", role: "developer"},
{id: 2, name: "Bob Smith", role: "designer"},
{id: 3, name: "Charlie Brown", role: "manager"}
];
// Create write stream
const writeStream = fs.createWriteStream('output.jsonl');
// Write each object
users.forEach(user => {
writeStream.write(JSON.stringify(user) + '\n');
});
writeStream.end();
console.log('File written successfully!');Common Mistakes to Avoid
Missing Newlines
{"id": 1}{"id": 2} ❌ WRONG!{"id": 1}
{"id": 2} ✅ CORRECT!Wrapping in Array
[
{"id": 1},
{"id": 2}
] ❌ That's JSON, not JSONL!Multi-line JSON Objects
{
"id": 1,
"name": "Alice"
} ❌ Each object must be on ONE line!{"id": 1, "name": "Alice"} ✅ Correct!Trailing Comma
{"id": 1},
{"id": 2}, ❌ No commas between lines!{"id": 1}
{"id": 2} ✅ Just newlines!Quick Reference
Format Rules
- One JSON object per line
- Each line ends with newline (\n)
- No commas between lines
- No array wrapper
File Extensions
- .jsonl (recommended)
- .json (also works)
- .ndjson (same format)
- .jsonlines (valid)
When to Use
- Streaming data
- Large datasets
- ML training data
- Log files
Next Steps
Now that you understand the basics, explore these resources to master JSONL: