Converts JSON and JSONL files to CSV. Supports dot notation for nested fields, streaming for large files, deduplication, and flexible field selection.
git clone https://github.com/tomventa/json-to-csv
cd json-to-csv
make build # produces ./json-to-csv
make install # copies to /usr/local/bin (may require sudo)
json-to-csv [flags] [input-file]
Input defaults to stdin if no file is provided. Output defaults to stdout if -output is not set.
| Flag | Description |
|---|---|
-fields <list> |
Comma-separated list of fields to include. Supports dot notation for nested objects. Column order follows the order given. |
-all |
Include every field found in the input. Fields are sorted alphabetically. Mutually exclusive with -fields. |
-exclude <list> |
Comma-separated list of fields to exclude. Intended for use with -all, but also applies when combined with -fields. |
| Flag | Default | Description |
|---|---|---|
-output <file> |
stdout | Write CSV to this file. |
-delimiter <char> |
, |
CSV field delimiter. Must be a single character. |
-no-header |
false | Omit the header row. |
-null <string> |
(empty) | Value to write when a field is missing or null. |
| Flag | Description |
|---|---|
-dedup |
Skip rows that are duplicates of a previously written row. |
-dedup-key <list> |
Comma-separated fields to use as the uniqueness key. When not set, the entire row is used. Requires -dedup. |
| Flag | Default | Description |
|---|---|---|
-format <value> |
auto |
Force input format. Accepted values: auto, json, jsonl. When auto, the format is detected from the first non-whitespace character: [ means JSON array, anything else means JSONL. |
Nested object fields are addressed with . as separator.
Given this record:
{ "_id": "abc", "shipping_address": { "firstname": "Ada", "zipcode": "10001" } }The field path shipping_address.firstname extracts Ada.
Paths can be arbitrarily deep: a.b.c.d.
Values that are arrays or objects (not further traversed) are serialized as a JSON string in the output cell.
Extract specific fields from a JSON array file:
json-to-csv -fields _id,shipping_address.firstname,shipping_address.zipcode orders.json
Include all fields from a JSONL file:
json-to-csv -all data.jsonl
All fields except two:
json-to-csv -all -exclude __v,internal_notes data.json
Use a tab delimiter:
json-to-csv -fields id,name,email -delimiter $'\t' users.jsonl
Deduplicate by a single field:
json-to-csv -fields email,name -dedup -dedup-key email users.jsonl
Deduplicate by multiple fields:
json-to-csv -fields country,city,name -dedup -dedup-key country,city data.json
Write to a file, replace empty fields with NULL:
json-to-csv -fields id,amount,status -null NULL -output out.csv transactions.jsonl
Pipe from stdin:
cat records.jsonl | json-to-csv -fields id,name -output out.csv
Large files and -all
When -all is used with a file, the tool performs two passes: the first to collect all field names, the second to write rows. The file is read twice.
When -all is used with stdin, all records are buffered in memory before writing, since stdin cannot be rewound.
When -fields is used (with file or stdin), only a single pass is performed.
Deduplication memory
Deduplication stores seen keys in memory. For very large inputs with many unique rows, memory usage will scale with the number of unique keys.
Number formatting
Integer-valued JSON numbers (e.g. 42.0) are written without a decimal point. Floating-point values are written with full precision.