CSV to JSON converter

Spreadsheets export CSV; web apps and APIs want JSON. This script reads a CSV file whose first row holds the column names and writes a JSON list with one object per row. It only uses the standard library, so it runs anywhere Python 3 is installed.

Usage

python3 csv2json.py people.csv                     # print JSON to the terminal
python3 csv2json.py people.csv -o people.json      # write to a file
python3 csv2json.py export.csv -d ';' --types      # semicolon-separated, detect numbers
python3 csv2json.py --help

Given this input:

name,age,city,score
Ana,34,Lisbon,9.5
Ben,,Oslo,7

--types produces {"name": "Ana", "age": 34, "city": "Lisbon", "score": 9.5} and turns Ben’s empty age into null. Without --types, every value stays a string exactly as written in the file, which is the safe choice for things like postal codes or phone numbers with leading zeros.

The script

#!/usr/bin/env python3
"""Convert a CSV file to JSON (an array of objects, one per row)."""
import argparse
import csv
import json
import math
import sys
from pathlib import Path


def convert_value(text):
    if text == "":
        return None
    try:
        return int(text)
    except ValueError:
        pass
    try:
        number = float(text)
    except ValueError:
        return text
    return number if math.isfinite(number) else text


def read_rows(path, delimiter, infer_types):
    with path.open(newline="", encoding="utf-8-sig") as f:
        reader = csv.DictReader(f, delimiter=delimiter)
        for row in reader:
            if infer_types:
                yield {key: convert_value(value) for key, value in row.items()}
            else:
                yield row


def main():
    parser = argparse.ArgumentParser(description="Convert CSV to JSON.")
    parser.add_argument("csv_file", type=Path, help="input CSV file")
    parser.add_argument("-o", "--output", type=Path, help="output JSON file (default: print to stdout)")
    parser.add_argument("-d", "--delimiter", default=",", help="field separator (default: ,)")
    parser.add_argument("--types", action="store_true", help="turn numbers into numbers and empty cells into null")
    parser.add_argument("--indent", type=int, default=2, help="JSON indentation (default: 2)")
    args = parser.parse_args()

    if not args.csv_file.is_file():
        sys.exit(f"error: {args.csv_file} is not a file")

    rows = list(read_rows(args.csv_file, args.delimiter, args.types))
    text = json.dumps(rows, indent=args.indent, ensure_ascii=False)

    if args.output:
        args.output.write_text(text + "\n", encoding="utf-8")
        print(f"Wrote {len(rows)} rows to {args.output}", file=sys.stderr)
    else:
        print(text)


if __name__ == "__main__":
    main()

How it works

• csv.DictReader uses the header row as keys and handles quoted fields that contain commas or line breaks. Never split CSV lines with line.split(","); quoting breaks it.
• The file is opened with newline="", which the csv module requires, and encoding="utf-8-sig", which reads normal UTF-8 and also strips the invisible byte-order mark that Excel adds to UTF-8 exports.
• convert_value tries int, then float, and keeps the original text otherwise. Values like nan or inf stay text, because JSON has no way to represent them.
• ensure_ascii=False keeps accented characters readable in the output instead of \u escapes.
• Messages go to standard error and data to standard output, so python3 csv2json.py data.csv > data.json produces a clean file.

Ideas to extend it

Read from standard input when the file name is -, add a --jsonl flag that writes one object per line for very large files, or flip the direction with csv.DictWriter to export JSON back to CSV.