Getting Started with jq

Learn to slice, filter, and transform JSON data — in 5 minutes.

What is jq?

jq is a lightweight command-line tool for processing JSON. Think of it as grep + sed + awk — but for structured data.

If you've ever stared at a wall of JSON from an API and thought "I just want the names" — jq is your answer.

Terminal
$ curl -s api.github.com/users/Mickhat | jq '{login, repos: .public_repos}'
{
  "login": "Mickhat",
  "repos": 22
}

Install jq

macOS brew install jq
Ubuntu / Debian sudo apt install jq
Arch Linux sudo pacman -S jq
Windows scoop install jq

Or skip installation entirely — the playground on this site runs jq server-side. Just start typing!

Your First 5 Filters

All examples below are interactive. Edit the filter and watch the output change in real-time.

1

The identity filter: .

A dot (.) means "the whole input". It passes data through unchanged — like cat for JSON.

jq 

              

            

          


          

            
2

            

              
Access a field: .name

              
Dot + field name extracts a single value. Try .age or .city.

              

                

                  jq
                  
                

                

              

            

          


          

            
3

            

              
Iterate arrays: .[]

              
Square brackets after a dot unpack every element from an array.

              

                

                  jq
                  
                

                

              

            

          


          

            
4

            

              
Pipe it: .users[] | .name

              
The pipe | chains filters — output of the left becomes input of the right. Just like shell pipes.

              

                

                  jq
                  
                

                

              

            

          


          

            
5

            

              
Filter with select: select(.age > 25)

              
select() keeps only elements that match a condition. Combine it with pipes for powerful queries.

              

                

                  jq
                  
                

                

              

            

          

        


        

          
What's next?

          

            

              📚
              
57 Lessons

              
From basics to advanced — with exercises for every topic.

            

            

              🏆
              
Challenges

              
Test your skills with real-world data transformation problems.

            

            

              ⚡
              
Playground

              
Paste your own JSON and experiment freely.

            

            

              💡
              
Explainer

              
Paste any jq filter and get a step-by-step breakdown.

            

          

        


        

          
        

      

    

  


  
  

    
    

      

        
Welcome to learnjq

        
Select a lesson from the sidebar to begin.

      

      

      

        

          

            

              📄 JSON Input
              
            

            
          

          

            

              🔧 jq Filter
              💡 Hint
            

            
            
          

          

            

              📤 Output
              
            

            

          

          

            

              🎯 Expected Output
            

            

          

        

        

          
          
        

      

    

  


  
  

    

      

        

          📄 JSON Input
          

            
            
            
          

        

        
      

      

        

          🔧 jq Filter
          

            
            
            
            
          

        

        
        

      

      

        

          📤 Output
          

            
            
          

        

        
Type a jq filter and press Enter to see results...

      

    

  


  
  

    

      
      

        

          
Select a challenge

          
        

        

        

          

            
📄 Input

            

          

          

            

              🔧 Your Solution
              
            

            
          

          

            
📤 Your Output

            

          

          

            
🎯 Expected

            

          

        

        
      

    

  


  
  

    

      

        

          📄 JSON Input
          
        

        
      

      

        
        
        
      

      

        

          
🔬 Pipe Visualizer

          
Enter a jq filter with pipes (|) and click Visualize to see the data transformation step by step.

          

            
Try these:

            
            
            
            
            
          

        

      

    

  


  
  

    

      

        
        
      

      

        

          
💡 Filter Explainer

          
Type any jq expression above and each part will be annotated with an explanation.

          
Like explainshell.com — but for jq.

          

            
Try these: