Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

node-jq logo

node-jq is a Node.js wrapper for jq - a lightweight and flexible command-line JSON processor


$ npm install node-jq --save
# or
$ yarn add node-jq

Advanced installation

By default, node-jq downloads jq during the installation process with a post-install script. Depending on your SO downloads from [] into ./node_modules/node-jq/bin/jq to avoid colisions with any global installation. Check #161 #167 #171 for more information. You can safely rely on this location for your installed jq, we won't change this path without a major version upgrade.

If you want to skip the installation step of jq, you can set NODE_JQ_SKIP_INSTALL_BINARY to true or ignore the post-install script from the installation npm install node-jq --ignore-scripts.

npm install node-jq
npm install node-jq --ignore-scripts


jq example

Usually in your CLI using jq:

jq ".abilities[].moves" bulbasaur.json

and you get

  "name": "heartgold-soulsilver",
  "power": "10"
  "name": "platinum",
  "power": "50"
  "name": "diamond-pearl",
  "power": "99"

node-jq equivalent

With node-jq you could run it programmatically and interact with the output as a JavaScript Object:

NOTE: Take care of the filter that you are using with jq, mapping an array or any other iterative output isn't a valid JavaScript Object, that might fail at parse-time.

const jq = require('node-jq')

const filter = '.abilities[].moves'
const jsonPath = '/path/to/bulbasaur.json'
const options = {}, jsonPath, options)
  .then((output) => {
        "name": "heartgold-soulsilver",
        "power": "10"
        "name": "platinum",
        "power": "50"
        "name": "diamond-pearl",
        "power": "99"
  .catch((err) => {
    // Something went wrong...


path to jq binary

By default, the jq binary installed with the package is used. If you have special needs or want to use another binary in a different path you can set the environment variable JQ_PATH to override the binary path.


Description Type Values Default
Type of input string 'file', 'json', 'string' 'file'

input: 'file'

Run the jq query against a JSON file.'.', '/path/to/file.json').then(console.log)
// { "foo": "bar" }

input: 'file' with multiple files

Run jq query against multiple JSON files.'.', ['/path/to/file.json','path/to/other_file.json']).then(console.log)
// { "foo": "bar" }
// { "otherFoo": "andBar" }

input: 'json'

Run the jq query against an Object.'.', { foo: 'bar' }, { input: 'json' }).then(console.log)
// { "foo": "bar" }

input: 'string'

Run the jq query against a String.'.', '{ foo: "bar" }', { input: 'string' }).then(console.log)
// { "foo": "bar" }


Description Values Default
Type of output 'pretty', 'json', 'compact', 'string' 'pretty'

output: 'pretty'

Return the output as a String.'.', '/path/to/file.json', { output: 'string' }).then(console.log)
// {
//   "foo": "bar"
// }

output: 'json'

Return the output as an Object.'.', '/path/to/file.json', { output: 'json' }).then(console.log)
// { foo: 'bar' }

output: 'compact'|'string'

Return the output as a String.'.', '/path/to/file.json', { output: 'compact' }).then(console.log)
// {"foo":"bar"}'.', '/path/to/file.json', { output: 'string' }).then(console.log)
// {"foo":"bar"}


Description Values Default
Read input stream into array true, false false

slurp: true

Read input stream into array.'.', ['/path/to/file.json','/path/to/other_file.json'], { output: 'json', slurp: true }).then(console.log)
// [
//   {
//     "foo": "bar"
//   },
//   {
//     "otherFoo": "andBar"
//   }
// ]


Description Values Default
Sort object keys in alphabetical order true, false false

sort: true

Sorts object keys alphabetically.'.', ['/path/to/file.json'], { output: 'json', sort: true }).then(console.log)
// {
//   "a": 2,
//   "b": 1
// },

Projects using node-jq


Why would you want to manipulate JavaScript Objects with jq inside a nodejs app, when there are tools like ramda or lodash?

The idea was to port jq in node to be able to run it as-is. node-jq doesn't try to replace Array/Object filters, maps, transformations, and so on.

Our primary goal was to make jq syntax available inside an Atom extension: atom-jq.

Other than that, jq is an interesting CLI tool to quickly parse and manipulate the response of an API, such as:

curl '' | jq '.[].postId'

There are also people dealing with complex use-cases, and some of them want to port their bash scripts to node:

Want to learn jq?

Seems hard to learn, but it really isn't.

jq is like sed for JSON. Slice, filter, map and transform structured data in a simple and powerful way.

Take a look at this great introduction or a jq lesson.

You can check out the official manual and fiddle around in the online playground