Products SEO & GEO Agent Paid Ads Agent Website Agent Conversion Agent
How it works Pricing FAQ Blog Book a call

JSONL files: how to create one for AI uploads, step by step

Updated · 7 min read

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 call

How 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.

StepWhat to doWhere it goes wrong
1. Get the target formatRead the upload page of the platform you're sending it toEvery platform names its fields differently
2. Save your data as CSVOne row per example, one column per field, headers in row 1Merged cells and notes below the table become junk rows
3. Convert with PythonA three-line script writes one JSON object per rowWriting the whole list as one JSON array instead
4. Check every linePython's built-in checker reads each line and stops at the first bad oneA 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 JSONJSONL
ShapeOne big object or array, often across many linesOne object per line, no outer brackets, no commas between lines
Read by a programUsually all at onceOne line at a time
Add a recordEdit inside the arrayAdd a line at the end
One broken recordThe whole file fails to parseThat 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.

PlatformWhat the JSONL is forKey limits (November 2026)
OpenAI Batch APIMany requests at once; each line needs a unique custom_id50% cheaper than normal calls; done within 24 hours; up to 50,000 requests and 200 MB per file; one model per file
Gemini API BatchMany requests at once; each line has a key and a request50% 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 StorageGoogle suggests starting with 100 examples
Amazon BedrockFine-tuning; format depends on the modelSize rules per model
Microsoft FoundryFine-tuning; separate training and validation files, one conversation per lineExample and size minimums per model
OpenAI fine-tuningClosing; see belowAt 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:

  1. `import csv, json`
  2. `rows = csv.DictReader(open("faq.csv", encoding="utf-8-sig", newline=""))`
  3. `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:

PieceWhy it's there
csv.DictReaderTurns each row into a record, using row 1 as field names
utf-8-sigPython'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=FalseKeeps 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 seeUsual causeFix
Expecting valueA blank line, often at the end of a pasted fileDelete empty lines
Expecting property name enclosed in double quotesSingle quotes or a trailing comma, from hand typingGenerate lines with the script, not by hand
Upload rejected, format looks rightField names don't match the platformCompare one line with the platform's example
UnicodeDecodeError when the script runsCSV saved in an older encoding, not UTF-8Re-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?

Keep learning

NextPrompt optimization tools: the best picks for businessWhich tools rewrite and improve AI prompts, what each costs, and why most small businesses need only a free method plus a saved project.

Ask us one question

One line is enough. We reply by email.

Sources

  1. JSON Lines: format specification (jsonlines.org)
  2. OpenAI API docs: Supervised fine-tuning
  3. OpenAI API docs: Batch API
  4. Google AI Studio docs: Batch API
  5. Google Cloud: Prepare supervised fine-tuning data for Gemini models
  6. Amazon Bedrock User Guide: Prepare data for fine-tuning your models
  7. Microsoft Learn: Fine-tune a model with supervised fine-tuning in Microsoft Foundry
  8. Python 3 documentation: json module (including json.tool)
  9. Python 3 documentation: codecs, utf-8-sig
  10. pandas documentation: read_json
  11. pandas documentation: DataFrame.to_json