How to Use jq Command in Linux: The JSON Processing Tool Every Admin Needs

If you’ve ever tried to parse JSON output from an API using grep and awk, you know the pain. The jq command in Linux is the tool that finally makes JSON processing make sense. It is lightweight, fast, and once you learn it, you will wonder how you ever lived without it.

In this guide, I will walk you through everything you need to know about using jq effectively. From basic syntax to real-world examples, you will be parsing JSON like a pro by the end.

What is jq?

jq is a lightweight command-line JSON processor. Think of it as sed command or awk command, but specifically designed for JSON specification data.

Here is what makes jq special:

• Zero runtime dependencies: Written in portable C, it runs anywhere
• JSON-aware: Unlike grep, it actually understands JSON structure
• Powerful filtering: Extract, transform, and manipulate JSON with simple expressions
• Pipe-friendly: Integrates perfectly with curl, docker, and other CLI tools

For DevOps engineers, sysadmins, and developers working with APIs, jq is often indispensable. Modern infrastructure runs on JSON – Docker, Kubernetes, cloud APIs, application logs. jq speaks that language fluently.

Get a VPS from as low as $11/year! WOW!

Why You Need jq (And How I Discovered It)

I remember the exact moment I found jq. It was 2 AM, and I was trying to parse a massive JSON response from an AWS API call. I had a chain of grep, cut, and sed commands that looked like someone had a keyboard seizure. And it still was not working.

My terminal history was a graveyard of failed attempts. Every time I thought I had it, a nested object or an array would break everything. I was ready to just manually copy-paste what I needed.

Then someone in a Linux Discord mentioned jq. Five minutes later, I had a one-liner that did exactly what I needed. What took me three hours of grep wrestling took jq about 30 seconds to solve.

The reality is that the grep command does not understand JSON structure. It sees text. jq sees objects, arrays, keys, and values. That structural awareness changes everything.

Installing jq on Linux

Getting jq installed is straightforward on any major distro. For general concepts about installing software on Linux, check out our full guide. Here is the quick version for jq:

Ubuntu/Debian

sudo apt update
sudo apt install jq

RHEL/Fedora/CentOS

sudo dnf install jq

For older RHEL/CentOS systems using yum:

sudo yum install jq

Arch Linux

sudo pacman -S jq

Verifying Installation

Check that jq installed correctly:

jq --version

You should see something like jq-1.7.1 or jq-1.8.1 (the latest stable version as of 2025). You can also find the source code and report issues at the jq GitHub repository.

Understanding jq Syntax Basics

jq uses a filter-based syntax. You write expressions that transform input JSON into output. Let us start with the fundamentals.

The Identity Filter (.)

The simplest jq filter is just a dot. It outputs the input unchanged but pretty-printed:

echo '{"name":"alexa","distro":"arch"}' | jq '.'

Output:

{
  "name": "alexa",
  "distro": "arch"
}

This is incredibly useful for making minified JSON readable.

Accessing Fields

Use dot notation to access object fields:

echo '{"name":"alexa","distro":"arch"}' | jq '.name'

Output: "alexa"

For nested objects, chain the dots:

echo '{"user":{"name":"alexa","role":"admin"}}' | jq '.user.name'

Array Operations

Access array elements with square brackets:

echo '["arch","ubuntu","fedora"]' | jq '.[0]'

Output: "arch"

Get all array elements with .[]:

echo '["arch","ubuntu","fedora"]' | jq '.[]'

Pipe Operations

Chain filters together with the pipe operator:

echo '{"users":[{"name":"alexa"},{"name":"bob"}]}' | jq '.users[] | .name'

This extracts the users array, iterates through each element, then grabs the name field.

Practical jq Examples

Theory is nice, but let us see jq in action with real scenarios you will actually encounter.

Pretty-Printing JSON

Got minified JSON that is impossible to read? jq fixes that instantly:

curl -s https://api.github.com/users/torvalds | jq '.'

The -s flag on curl command silences progress output, giving you clean JSON for jq to process.

Extracting Specific Fields

Pull exactly what you need from a large JSON response:

curl -s https://api.github.com/users/torvalds | jq '{login, public_repos, followers}'

This creates a new object with only the fields you care about.

Filtering Arrays

The select() function lets you filter based on conditions:

curl -s https://api.github.com/orgs/octokit/repos | jq '.[] | select(.stargazers_count > 100) | .full_name'

This finds all repos with more than 100 stars and returns their names.

Working with API Responses

docker inspect $(docker ps -q) | jq '.[] | {name: .Name, ip: .NetworkSettings.IPAddress}'

Processing Log Files

Many applications output JSON-formatted logs. jq can extract specific fields:

cat app.log | jq -r 'select(.level == "ERROR") | .message'

The -r flag outputs raw strings without quotes – perfect for piping to other commands.

Transforming Data Structures

Convert JSON to different formats:

echo '[{"name":"alexa","score":95},{"name":"bob","score":87}]' | jq -r '.[] | [.name, .score] | @csv'

Output:

"alexa",95
"bob",87

Common jq Use Cases for System Administrators

Here is where jq really shines in day-to-day sysadmin work:

• Cloud API parsing: AWS, GCP, and Azure CLIs all output JSON. jq extracts exactly what you need.
• Container analysis: Parse docker inspect and kubectl output for specific configuration details.
• Log analysis: Filter JSON-formatted logs by severity, timestamp, or custom fields.
• CI/CD automation: Validate JSON configs and extract values in Bash scripting pipelines.
• Config management: Extract and transform settings from JSON configuration files.

Advanced jq Techniques

Once you are comfortable with the basics, these techniques will level up your jq skills.

Conditional Logic (if-then-else)

Add logic to your filters:

echo '[{"name":"server1","status":"running"},{"name":"server2","status":"stopped"}]' | jq '.[] | if .status == "running" then .name + " is UP" else .name + " is DOWN" end'

Custom Functions

Define reusable functions for complex operations:

jq 'def double: . * 2; [1, 2, 3] | map(double)'

For complete syntax documentation, the official jq manual covers everything.

Multiple Filters

Run multiple filters and combine results:

echo '{"a":1,"b":2,"c":3}' | jq '{sum: (.a + .b + .c), count: (keys | length)}'

Common Mistakes and How to Avoid Them

Tips for Mastering jq

After years of using jq daily, here is my advice for getting good at it:

1. Start with the identity filter: Pipe your JSON through jq '.' first to see what you are working with.
2. Use jqplay.org: This interactive playground lets you test filters without leaving your browser.
3. Keep filters readable: Complex one-liners impress nobody. Break them into multiple piped filters if needed.
4. Combine with other tools: jq works beautifully with curl, xargs, and other Linux commands.
5. Read the docs: The jq man page is excellent. Use man jq or check it online.

Start Parsing JSON Today

The jq command transforms JSON parsing from a frustrating chore into something genuinely satisfying. Once you internalize the basic syntax, you will find yourself reaching for it constantly.

I use jq every single day in my homelab. Whether I am checking container health, parsing API responses, or analyzing logs, jq makes the job faster and more reliable than any grep chain ever could.

Start simple. Install jq, pipe some JSON through it, and experiment with basic filters. The investment pays off immediately.

Looking to expand your Linux command-line skills? Check out our guides on awk command for text processing and Bash scripting for automating your workflows.

Alexa Velinxs

I'm Alexa Velinxs, a cryptocurrency trading expert passionate about demystifying digital assets for both beginners and seasoned investors. Through my writing, I share actionable strategies, market insights, and practical tips to help you navigate the crypto landscape with confidence. Let's explore the future of finance together.

See Full Bio