Process and Highlight JSON with jq

Once you know enough command-line basics, it’s time to actually learn some useful stuff that you can apply in your daily work! Since JSON is super ubiquitous, I’d like to teach you some useful command-line JSON processing voodoo first.

The jq command-line tool

The jq tool is usually not installed by default. Recent versions of macOS come with it, but on most systems you’ll need to install it yourself:

# macOS, with Homebrew
$ brew install jq

# Debian and Ubuntu
$ sudo apt install jq

# Windows
$ winget install jqlang.jq

The jq download page lists options for other systems.

A very basic example of jq usage is this:

$ echo '{ "Price": 10.0, "Name": "Cable" }' | jq

The result is a well-formatted, colorized version of the JSON you feed it:

jq pretty-printing and colorizing JSON in a terminal
Colorizing JSON with jq

I actually use it a lot for this purpose. If you just want to view the content of a JSON file, a simple jq . filename.json will instantly help you out. But jq can do so much more: it’s a full-fledged command-line JSON processor.

Say, for example, that you are only interested in the price field. You can simply obtain the price with the following command:

$ echo '{ "Price": 10.0, "Name": "Cable" }' | jq ".Price"
10.0

Try it! Since version 1.7, jq keeps the number exactly as it appears in the input, so you get 10.0. Older versions print 10.

More jq filters

The .Price part is called a filter. Let’s try a few more on a file called products.json that contains a list of products:

[
  { "Name": "Cable", "Price": 10, "InStock": true },
  { "Name": "Charger", "Price": 25, "InStock": false },
  { "Name": "Mouse", "Price": 15, "InStock": true }
]

With .[], you go over every element of a list. Combine it with a field name to get that field from each element:

$ jq '.[].Name' products.json
"Cable"
"Charger"
"Mouse"

The output is still JSON, hence the quotes. If you want plain text, for example to use in a shell script, add the -r (raw output) option:

$ jq -r '.[].Name' products.json
Cable
Charger
Mouse

Like in a Unix pipe, you can chain filters with |. The select() filter only lets through the elements for which a condition is true. Here, we get the names of the products that are in stock:

$ jq '.[] | select(.InStock) | .Name' products.json
"Cable"
"Mouse"

And jq can calculate, too. This adds up all the prices:

$ jq 'map(.Price) | add' products.json
50

This is still just touching the very basics. Just remember that jq exists and that you can get pretty much anything from your JSON files with it. The jq manual has many more examples.

Python-based alternatives

Using Python’s JSON library

Python’s JSON library can also be used from the command-line, to validate and pretty-print your JSON:

$ echo '{ "name": "Monty", "age": 45 }' | python3 -m json
{
    "name": "Monty",
    "age": 45
}

Since Python 3.14, you can run the module as python3 -m json, and in a terminal, it colors its output just like jq does. On older versions, use python3 -m json.tool, which still works. If you only need to pretty-print or validate JSON, this saves you installing jq. It can’t query or filter the data, though.

Advanced JSON queries in Python

If you are looking for advanced ways to query JSON from within Python, head over to our page on querying JSON in Python with JMESPath.

Related articles

Leave a Comment