Tutorials

Format JSON in the Terminal: jq, Python, Node

DevUtilHub Team
6 min read
Terminal window printing an indented JSON document

Quick answer: if you have jq, run jq . file.json. If you donโ€™t, python3 -m json.tool file.json works on almost any Linux or macOS machine without installing anything.

jq . data.json
python3 -m json.tool data.json
curl -s https://api.github.com/repos/nodejs/node | jq .

Both print formatted JSON to stdout (jq indents with 2 spaces, Python with 4) and exit with an error if the input isnโ€™t valid JSON, so they double as validators. The sections below cover the options youโ€™ll use most: indentation, sorted keys, minifying, and editing files in place.

Working in an editor instead? See How to Format JSON in VS Code. For a one-off paste, the JSON Formatter is quicker.

jq

jq is the standard tool for JSON in the shell. Install it with brew install jq, sudo apt install jq, or winget install jqlang.jq.

jq . data.json              # pretty-print, 2-space indent, colored in a terminal
jq --indent 4 . data.json   # 4-space indent
jq --tab . data.json        # tabs
jq -S . data.json           # sort keys
jq -c . data.json           # minify to one line

The . is a filter meaning โ€œthe whole inputโ€. Once the output is readable, you can swap it for a real filter to pull out what you need, for example jq '.items[].name' data.json.

jq has no in-place flag. Write to a temporary file and move it back:

jq . data.json > data.tmp && mv data.tmp data.json

Donโ€™t write jq . data.json > data.json. The shell empties the file before jq reads it, and you lose the data.

Python

Every recent Python 3 includes the json.tool module:

python3 -m json.tool data.json                  # 4-space indent by default
python3 -m json.tool --indent 2 data.json
python3 -m json.tool --sort-keys data.json
python3 -m json.tool --compact data.json        # minify
cat data.json | python3 -m json.tool            # from stdin

--indent and --compact need Python 3.9 or newer. By default non-ASCII characters are escaped (รฉ becomes รฉ). Add --no-ensure-ascii to keep them as they are.

To write the result back to the same file, give json.tool an output path. Current versions read the whole input before opening the output, so this works (unlike the jq redirect above):

python3 -m json.tool data.json data.json

Node.js

If Node is installed and Python isnโ€™t, a one-liner does the job:

node -e 'process.stdout.write(JSON.stringify(JSON.parse(require("fs").readFileSync(0, "utf8")), null, 2) + "\n")' < data.json

Change the 2 to set the indentation, or drop , null, 2 to minify. Wrap it in a shell alias if you use it often.

Prettier, for whole projects

When you want every JSON file in a repository to look the same, use Prettier instead of formatting files one at a time:

npx prettier --write "**/*.json"   # format in place
npx prettier --check "**/*.json"   # fail if anything is unformatted (CI)

Prettier skips anything in .gitignore and .prettierignore. Its layout differs a bit from jq and Python: short arrays stay on one line. Prettier vs VS Codeโ€™s Built-in JSON Formatter shows the difference.

Platform extras

  • macOS ships json_pp, so json_pp < data.json works with no installs.
  • PowerShell: Get-Content data.json -Raw | ConvertFrom-Json | ConvertTo-Json -Depth 100. Donโ€™t skip -Depth. The default depth is 2, and anything nested deeper gets flattened into a string without an error.

Which one to use

Need Command
Read an API response curl -s URL | jq .
Validate a file in a script jq empty data.json (no output, non-zero exit on bad JSON)
Sort keys before comparing jq -S . a.json
Minify jq -c . data.json
No installs allowed python3 -m json.tool data.json
Every JSON file in a repo npx prettier --write "**/*.json"

To compare two JSON files, sort both and diff them: diff <(jq -S . a.json) <(jq -S . b.json). If youโ€™d rather see the result side by side with highlighting, paste both into JSON Diff, which sorts keys automatically.

Tags

#json #command-line #jq #python #nodejs

Share this article

Related Articles