Developer Tools 12 min read

How to Convert CSV to JSON — A Complete Guide

Learn how CSV and JSON differ, when to convert between them, and how to do it correctly in the browser, Python, Node.js, and the command line.

Quick Answer

CSV to JSON conversion maps each row of a comma-separated (or tab/semicolon-separated) file to a JSON object, using the header row as keys. A three-row CSV with columns name, email, age becomes a JSON array of three objects, each with name, email, and age fields.

The fastest way: paste your data into a CSV to JSON converter. For scripts and automation, use Python's built-in csv + json modules or Miller (mlr).

What Is CSV?

CSV (Comma-Separated Values) is a plain text format for tabular data. Each line represents a record, and fields within a line are separated by a delimiter — typically a comma, but sometimes a semicolon, tab, or pipe.

Example CSV:

name,email,age
Alice,[email protected],28
Bob,[email protected],34
"Carol, Jr.",[email protected],31

Key characteristics:

  • Flat structure: Rows and columns only. No nesting.
  • No data types: Every value is text. "28" is a string, not a number.
  • Quoting rules (RFC 4180): Fields containing delimiters, newlines, or quotes are wrapped in double quotes. A literal quote inside a quoted field is escaped by doubling it: "".
  • No standard encoding: Files may be UTF-8, Windows-1252, or ISO-8859-1 depending on the export source.

CSV is the most universally supported data exchange format. Every spreadsheet, database, and programming language can read and write it.

What Is JSON?

JSON (JavaScript Object Notation) is a hierarchical text format for structured data. It supports objects (key-value pairs), arrays (ordered lists), strings, numbers, booleans, and null.

The same data in JSON:

[
  { "name": "Alice", "email": "[email protected]", "age": 28 },
  { "name": "Bob", "email": "[email protected]", "age": 34 },
  { "name": "Carol, Jr.", "email": "[email protected]", "age": 31 }
]

Key differences from CSV:

  • Hierarchical: Objects can contain other objects and arrays to any depth.
  • Typed values: Numbers, booleans, and null are distinct from strings.
  • Self-describing: Keys are part of the data, not a separate header row.
  • Standardized: JSON follows RFC 8259 strictly. Parsers are consistent across languages.

JSON is the default format for REST APIs, NoSQL databases, and modern application configuration.

Why Convert CSV to JSON?

Common scenarios where you need this conversion:

  1. API integration: You have data in a spreadsheet and need to send it to a REST API that accepts JSON request bodies.
  2. Database import: NoSQL databases like MongoDB expect JSON (or BSON). Convert your CSV export to JSON before importing with mongoimport --jsonArray.
  3. Web applications: JavaScript applications work natively with JSON via JSON.parse(). Loading CSV requires an additional parsing step.
  4. Static site generators: Tools like Eleventy, Gatsby, and Hugo use JSON data files for dynamic content. Convert a spreadsheet of products, FAQs, or team members into JSON.
  5. Data pipelines: Transform flat CSV data into structured JSON for downstream processing, enrichment, or storage.
  6. Configuration generation: Turn a spreadsheet of feature flags, environment variables, or translations into a structured JSON config file.

How CSV to JSON Conversion Works

The conversion follows these steps:

  1. Detect the delimiter — comma, semicolon, tab, or pipe. Auto-detection looks at the first few rows for consistent field counts.
  2. Parse rows — split the text into records, handling quoted fields and escaped quotes per RFC 4180.
  3. Extract headers — if the first row contains column names, use them as JSON object keys.
  4. Map rows to objects — each subsequent row becomes a JSON object with keys from the header and values from the row's fields.
  5. Output JSON — serialize the array of objects (or arrays) as formatted JSON.

Output Format Options

Array of objects (most common):

[
  { "name": "Alice", "age": "28" },
  { "name": "Bob", "age": "34" }
]

Best for: APIs, databases, any system that expects named fields.

Array of arrays:

[
  ["name", "age"],
  ["Alice", "28"],
  ["Bob", "34"]
]

Best for: Data without headers, preserving exact row/column structure, or when column position matters more than names.

Handling Edge Cases

Quoted Fields

Fields containing the delimiter character, newlines, or double quotes must be enclosed in double quotes:

"Smith, Jr.",Main St,"She said ""hello"""

This parses as three fields:

  • Smith, Jr.
  • Main St
  • She said "hello"

A proper parser tracks whether it's inside a quoted field. Splitting on commas naively will break this.

European Semicolon-Delimited CSV

In locales where the comma is the decimal separator (Germany, France, etc.), spreadsheets export CSV with semicolons:

product;price;stock
Widget;12,50;100
Gadget;8,99;250

Always check your delimiter. If your JSON output has single fields containing commas, you probably used the wrong delimiter.

Empty Fields and Missing Values

CSV represents missing values as empty fields: Alice,,28 has an empty email. In JSON, this maps to an empty string "". If you need JSON null for missing values, post-process the output.

Encoding Issues

Excel on Windows may export as Windows-1252 instead of UTF-8. Characters like é, ü, or em-dashes may appear garbled. Solutions:

  • Re-save as UTF-8 in your spreadsheet application
  • Use Python with encoding='utf-8-sig' to handle BOM (byte order mark)
  • Use iconv on the command line: iconv -f WINDOWS-1252 -t UTF-8 file.csv

Converting CSV to JSON in Code

Python (built-in — no install needed)

import csv
import json

with open('data.csv', 'r', encoding='utf-8') as f:
    reader = csv.DictReader(f)
    data = list(reader)

with open('data.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

One-liner for the command line:

python3 -c "import csv,json,sys; print(json.dumps(list(csv.DictReader(sys.stdin)),indent=2))" < data.csv > data.json

For semicolon-delimited files:

reader = csv.DictReader(f, delimiter=';')

JavaScript / Node.js

Using the csv-parse library (handles all edge cases):

import { parse } from 'csv-parse/sync';
import { readFileSync, writeFileSync } from 'fs';

const csv = readFileSync('data.csv', 'utf-8');
const records = parse(csv, { columns: true, trim: true });
writeFileSync('data.json', JSON.stringify(records, null, 2));

For browser-side conversion, PapaParse is the standard library:

const result = Papa.parse(csvString, { header: true });
const json = JSON.stringify(result.data, null, 2);

Miller (mlr) — purpose-built CLI tool

mlr --icsv --ojson cat data.csv > data.json

Miller handles delimiter detection, quoted fields, encoding, and large files efficiently. It's the best tool for command-line data format conversion.

jq (with pre-processing)

jq doesn't parse CSV natively, but combined with Miller or csvtool:

mlr --icsv --ojson cat data.csv | jq '.[0:5]'  # first 5 records

Type Conversion

CSV has no data types. After conversion, all values are JSON strings. If you need typed values:

Python

import csv, json

def auto_type(value):
    if value == '':
        return None
    try:
        return int(value)
    except ValueError:
        try:
            return float(value)
        except ValueError:
            if value.lower() in ('true', 'false'):
                return value.lower() == 'true'
            return value

with open('data.csv') as f:
    reader = csv.DictReader(f)
    data = [{k: auto_type(v) for k, v in row.items()} for row in reader]

JavaScript

function autoType(value) {
  if (value === '') return null;
  if (value === 'true') return true;
  if (value === 'false') return false;
  const num = Number(value);
  if (!isNaN(num) && value.trim() !== '') return num;
  return value;
}

Warning: Be careful auto-converting to numbers. Values like zip codes ("07102"), phone numbers, and product IDs may have leading zeros that are meaningful as strings but lost when parsed as numbers.

Common Mistakes

  1. Splitting on commas instead of proper parsing. line.split(',') breaks on quoted fields. Always use a CSV parser.
  2. Wrong delimiter. Check if your file uses semicolons (European), tabs (database exports), or pipes.
  3. Assuming UTF-8 encoding. Excel may export as Windows-1252. Check for garbled characters.
  4. Losing leading zeros. Auto-converting "007" to number 7 loses information. Keep as string unless you're certain it's a numeric value.
  5. Ignoring newlines inside fields. Multiline fields must be quoted. A line-by-line parser will create broken records.
  6. Not trimming whitespace. Some exports add spaces after delimiters: Alice, 28 has a leading space in the age field.
  7. BOM (Byte Order Mark). UTF-8 files from Excel may start with a BOM (\xEF\xBB\xBF), which can corrupt the first header name. Use encoding='utf-8-sig' in Python to handle this.

Performance: Browser vs. Command Line

Method Best for Approximate speed
Browser (this tool) Quick conversions, < 5 MB Instant to a few seconds
Python csv + json Scripting, automation ~50 MB/s on modern hardware
Miller (mlr) Large files, pipelines ~200 MB/s, stream-based
Node.js csv-parse Server-side processing ~100 MB/s with streaming

For files under a few megabytes, browser-based conversion is instant. For recurring tasks or large datasets, script it.

Frequently Asked Questions

How do I convert CSV to JSON?

Paste your CSV into a converter tool, select whether the first row is headers, and choose the output format. For automation, use Python (csv.DictReader + json.dumps), Node.js (csv-parse), or Miller (mlr --icsv --ojson).

What is the difference between CSV and JSON?

CSV is flat (rows and columns) with no data types — everything is text. JSON is hierarchical (nested objects and arrays) with typed values (strings, numbers, booleans, null). CSV is more compact for simple tables; JSON is more flexible for structured data.

Why are all my JSON values strings?

CSV has no type system. A converter preserves this by outputting everything as strings. To get numbers and booleans, post-process with type inference functions or use a converter that supports automatic type detection.

How do I handle semicolon-delimited CSV?

Specify the delimiter explicitly. In Python: csv.reader(f, delimiter=';'). In online tools: select "Semicolon" from the delimiter dropdown. Auto-detection in most tools handles this correctly.

What is RFC 4180?

The specification for CSV format. Key rules: comma-separated fields, CRLF line endings, double-quoted fields for values containing commas or quotes, doubled double-quotes for escaping. Many real-world files don't follow it perfectly.

How do I handle large CSV files?

Use command-line tools that stream data instead of loading everything into memory. Python's csv module and Miller (mlr) both handle files of any size. Browser-based tools are limited to a few megabytes.

Can I convert JSON back to CSV?

Yes — use a JSON to CSV converter. Flat JSON arrays convert cleanly. Nested JSON must be flattened first, which requires decisions about column naming (e.g., address.city or address_city).

What is TSV?

TSV (Tab-Separated Values) uses tabs instead of commas. Common for database exports and scientific data. Most CSV parsers support TSV by setting the delimiter to \t.

Does the browser tool store my data?

No. All processing runs client-side in JavaScript. Nothing is sent to any server, stored, or logged. The tool works offline after the page loads.

How do I add type inference to the conversion?

Write a post-processing step that checks each value: try parsing as a number, check for true/false strings, and map empty strings to null. Be cautious with leading zeros — zip codes and IDs should stay as strings.

Related Tools