JSONL files: how to create one for AI uploads, step by step
Short answer A JSONL file is plain text with one complete JSON object per line, saved as UTF-8 with a .jsonl ending. To make one, save your spreadsheet as CSV, run a short Python script that writes one line per row, then check every line parses. First confirm the exact fields your AI platform expects.
Want help applying this to your business? Talk it through on a free 30-minute call.
Book a callHow to create a JSONL file: the four steps
Start from a spreadsheet, end with a file an AI platform accepts. Python is free and needs no extra packages for this.
| Step | What to do | Where it goes wrong |
|---|---|---|
| 1. Get the target format | Read the upload page of the platform you're sending it to | Every platform names its fields differently |
| 2. Save your data as CSV | One row per example, one column per field, headers in row 1 | Merged cells and notes below the table become junk rows |
| 3. Convert with Python | A three-line script writes one JSON object per row | Writing the whole list as one JSON array instead |
| 4. Check every line | Python's built-in checker reads each line and stops at the first bad one | A blank line or a stray comma fails the whole upload |
What a JSONL file looks like
Each line is one record, and each record is complete on its own. The JSON Lines format has three rules: the file is UTF-8, each line is a valid JSON value, and lines end with a newline. Two details trip people up:
"a byte order mark (U+FEFF) must NOT be included" (JSON Lines specification)
"e.g. null is a valid value but a blank line is not." (JSON Lines specification)
A newline after the last record is "strongly recommended but not required." The usual extension is .jsonl.
| Regular JSON | JSONL | |
|---|---|---|
| Shape | One big object or array, often across many lines | One object per line, no outer brackets, no commas between lines |
| Read by a program | Usually all at once | One line at a time |
| Add a record | Edit inside the array | Add a line at the end |
| One broken record | The whole file fails to parse | That line fails; the rest still read |
A short line for a batch job looks like this, all on one line in the file:
{"custom_id": "faq-1", "method": "POST", "url": "/v1/responses", "body": {"model": "...", "input": "Write a 2-sentence answer: do you work Saturdays?"}}
Which AI tools ask for a JSONL file?
Mostly two jobs: training a model on your examples (fine-tuning) and sending many requests at once at a discount (batch). Check the platform's own page before you build, because the field names differ.
| Platform | What the JSONL is for | Key limits (November 2026) |
|---|---|---|
| OpenAI Batch API | Many requests at once; each line needs a unique custom_id | 50% cheaper than normal calls; done within 24 hours; up to 50,000 requests and 200 MB per file; one model per file |
| Gemini API Batch | Many requests at once; each line has a key and a request | 50% of standard cost; 24-hour target; input file up to 2 GB |
| Google Cloud (Gemini tuning) | Fine-tuning, one example per line, uploaded to Cloud Storage | Google suggests starting with 100 examples |
| Amazon Bedrock | Fine-tuning; format depends on the model | Size rules per model |
| Microsoft Foundry | Fine-tuning; separate training and validation files, one conversation per line | Example and size minimums per model |
| OpenAI fine-tuning | Closing; see below | At least 10 lines; OpenAI suggests starting with 50 |
OpenAI's fine-tuning is the case most old tutorials are built on, and it is shutting down:
"OpenAI is winding down the fine-tuning platform. The platform is no longer accessible to new users." (OpenAI API docs: Supervised fine-tuning)
Existing eligible customers can start training jobs until January 6, 2027, and the gpt-4.1 and gpt-4.1-mini fine-tuned models shut down on January 14, 2027. If you are new, build for Google Cloud, Bedrock or Foundry instead, or skip fine-tuning.
Do you need fine-tuning at all?
Often no. Most owner jobs, like answering FAQs in your voice or drafting quotes, work with a good prompt and a few examples pasted in. OpenAI's own guidance puts testing first: "Only invest in fine-tuning after setting up evals," and if 50 good examples change nothing, "rethink your task or prompt before adding training data." Start with better prompts and come back when they hit a wall.
Convert a spreadsheet to JSONL with Python
Save the sheet as CSV (in Excel, choose CSV UTF-8). Then run these lines in a file such as convert.py, changing the file names to yours:
- `import csv, json`
- `rows = csv.DictReader(open("faq.csv", encoding="utf-8-sig", newline=""))`
- `with open("faq.jsonl", "w", encoding="utf-8") as f: f.writelines(json.dumps(r, ensure_ascii=False) + "\n" for r in rows)`
What each part does:
| Piece | Why it's there |
|---|---|
| csv.DictReader | Turns each row into a record, using row 1 as field names |
| utf-8-sig | Python's docs say it skips the hidden byte-order mark if one sits at the start of the file, so your first column name stays clean |
| json.dumps(...) + "\n" | One record, then a line break: the whole JSONL rule |
| ensure_ascii=False | Keeps accents and non-English letters readable instead of escape codes |
| encoding="utf-8" | Writes UTF-8 without the mark the format forbids |
Already use pandas? One line does the same job: `pd.read_csv("faq.csv").to_json("faq.jsonl", orient="records", lines=True, force_ascii=False)`. The lines option only works with orient set to records, per the pandas documentation.
How to format fine-tuning examples
Chat-style training files wrap each example in a messages list: what the customer asked, and the answer you want back. This is the shape Microsoft Foundry shows. With a CSV of question and answer columns, change line 3 of the script to:
`with open("train.jsonl", "w", encoding="utf-8") as f: f.writelines(json.dumps({"messages": [{"role": "user", "content": r["question"]}, {"role": "assistant", "content": r["answer"]}]}, ensure_ascii=False) + "\n" for r in rows)`
Each row then becomes one line like:
{"messages": [{"role": "user", "content": "Do you work Saturdays?"}, {"role": "assistant", "content": "Yes, 8am to 2pm."}]}
Google's Gemini tuning uses different names (contents and parts, with an optional systemInstruction), so the same idea needs different keys there. Whatever the platform, use real questions and the answers your best staff member gives. Keep a separate set of examples out of training to test the result.
Check the file before you upload
Python ships a checker. Run this in a terminal:
`python3 -m json.tool --json-lines faq.jsonl`
It reads each line as its own JSON object (added in Python 3.8). If every line is fine, it prints them all. If not, it stops with an error; the last record printed is the last good line, so the problem is the next one.
| Error you see | Usual cause | Fix |
|---|---|---|
| Expecting value | A blank line, often at the end of a pasted file | Delete empty lines |
| Expecting property name enclosed in double quotes | Single quotes or a trailing comma, from hand typing | Generate lines with the script, not by hand |
| Upload rejected, format looks right | Field names don't match the platform | Compare one line with the platform's example |
| UnicodeDecodeError when the script runs | CSV saved in an older encoding, not UTF-8 | Re-save the CSV as CSV UTF-8 and rerun |
Can I make a JSONL file without Python?
Yes, for a handful of lines. Type them in a plain text editor (Notepad, TextEdit in plain text mode), one record per line, and save as UTF-8 with a .jsonl ending. Past 20 or so lines, hand typing invites the errors above.
Free online CSV-to-JSONL converters exist, but you upload your file to someone else's server. Training data often holds customer names, emails and job details, so read how you collected that data and what customers agreed to before sending it anywhere.
Example
A plumber's FAQ batch
Sixty common questions sit in a sheet. The owner saves it as CSV, converts it, wraps each row in a batch line with a custom_id, and sends one batch to draft website answers at half the normal price. The checker caught one blank line at the end first.
A salon training a reply style
Two hundred past replies to booking questions, cleaned of client names. The owner first tries a prompt with ten pasted examples; the drafts are already close enough. Fine-tuning is shelved.
A bookkeeper with an old OpenAI tutorial
The tutorial says to upload to OpenAI fine-tuning. The account is new, so the option isn't there. The same examples, renamed to Google's contents and parts fields, go to Google Cloud instead.
FAQ
What is the difference between JSON and JSONL?
JSON holds one object or array, often spread over many lines. JSONL holds one complete object per line, so programs can read and add records one at a time.
Can I open a JSONL file in Excel?
Not directly as rows. Convert it back with pandas (read_json with lines=True) and save as CSV, or open it in any text editor to read it.
How many examples do I need to fine-tune a model?
It depends on the platform. OpenAI's minimum was 10 lines with 50 suggested to start; Google suggests starting with 100 for Gemini tuning. Quality matters more than count on both.
Should I compress a large JSONL file?
The JSON Lines spec recommends gzip or bzip2 to save space. Upload uncompressed unless the platform's page says it accepts compressed files.
Different for you?
- You want AI to run tasks without you building files: see AI marketing automation setup.
- Your data includes customer details: check first-party data and consent first.
- You only need better AI output: start with AI marketing prompts or ChatGPT for marketing.
- You want answers like these on your site: see the Website agent.