jq

jq는 JSON 입력에 filter를 적용해 선택, 변환, 집계하는 command-line processor다.

• jq 프로그램은 입력을 받아 출력을 만드는 filter이며, 가장 단순한 filter .는 입력값을 그대로 출력한다.
• object field 선택, array 순회, 조건 필터링, 새 object 구성, 문자열·숫자 변환을 pipeline처럼 조합할 수 있다.
• shell에서 filter와 문자열은 의도하지 않은 expansion을 막도록 작은따옴표로 감싸는 것이 기본이다.
• 현재 공식 문서는 jq 1.8 계열을 기준으로 한다. 배포판 package는 더 오래된 버전일 수 있으므로 필요한 option의 지원 여부를 jq –version으로 확인한다.

jq 공식 다운로드 문서가 안내하는 배포판 repository package를 설치한다.

sudo apt-get update
sudo apt-get install jq

sudo dnf install jq

공식 다운로드 문서는 Fedora package를 안내하지만 RHEL용 DNF/YUM repository 명령은 별도로 제시하지 않는다. RHEL에서 배포판 package를 사용할 수 없다면 공식 다운로드 페이지에서 CPU architecture에 맞는 Linux binary와 release checksum을 확인한다.

brew install jq

winget install jqlang.jq

jq --version
jq --help

jq [OPTIONS] FILTER [FILE...]
jq [OPTIONS] --args FILTER [STRING...]
jq [OPTIONS] --jsonargs FILTER [JSON_TEXT...]

• jq [OPTIONS] FILTER [FILE…]
• jq –args FILTER [STRING…]
• jq –jsonargs FILTER [JSON_TEXT…]
• FILE을 생략하면 standard input에서 JSON text stream을 읽는다.
• 하나의 input에서 filter가 여러 결과를 만들 수 있으며 각 결과는 별도의 JSON value로 출력된다.

• -n, –null-input: 입력을 읽지 않고 null에 filter를 한 번 실행한다.
• -R, –raw-input: JSON parsing 없이 각 입력 line을 string으로 읽는다.
• -s, –slurp: 모든 입력값을 하나의 array로 모은 뒤 filter를 한 번 실행한다.
• –stream: 큰 JSON을 path와 leaf value의 stream 형태로 처리한다.
• –seq: ASCII RS로 구분된 JSON text sequence를 읽고 쓴다.

• -c, –compact-output: 결과 하나를 한 line의 compact JSON으로 출력한다.
• -r, –raw-output: string 결과를 JSON quote 없이 출력한다.
• –raw-output0: string 결과 뒤에 newline 대신 NUL을 출력한다. newline을 포함할 수 있는 filename 처리에 유용하며 jq 1.7 이상이 필요하다.
• -j, –join-output: –raw-output처럼 출력하되 결과 사이에 newline을 넣지 않는다.
• -a, –ascii-output: non-ASCII 문자를 escape한 ASCII JSON으로 출력한다.
• -S, –sort-keys: object key를 정렬한다.
• -C, –color-output, -M, –monochrome-output: 색상 출력을 강제하거나 비활성화한다.
• –tab, –indent N: pretty-print indentation을 조정한다. N은 7 이하여야 한다.

• –arg NAME VALUE: string value를 $NAME에 안전하게 전달한다.
• –argjson NAME JSON_TEXT: parsing한 JSON value를 $NAME에 전달한다.
• –slurpfile NAME FILE: file의 JSON text들을 array로 읽어 변수에 넣는다.
• –rawfile NAME FILE: file 전체를 string으로 읽어 변수에 넣는다.
• -f, –from-file FILE: command line 대신 file에서 jq program을 읽는다.
• -L, –library-path DIRECTORY: module 검색 경로를 지정한다. 사용하면 built-in 검색 목록은 사용하지 않는다.

• -e, –exit-status: 마지막 결과가 false 또는 null이면 1, 결과가 없으면 4, 그 밖에는 0을 반환한다.
• -V, –version: version을 출력한다.
• –build-configuration: build 설정을 출력한다. 출력 형식은 안정된 API가 아니다.
• -h, –help: 도움말을 출력한다.
• –: option parsing을 끝내고 뒤의 값을 positional argument로 취급한다.

• ., .name, .nested.value: 입력 전체 또는 object field 선택
• .items[], .items[]?: array/object value 순회. ?는 type·missing error를 억제한다.
• select(CONDITION): 조건이 참인 값만 통과
• map(FILTER): array 각 항목에 filter 적용
• keys, length, type: key, 길이, JSON type 확인

• {name: .user.name, id}: 기존 값을 새 object로 구성. id는 id: .id의 축약형이다.
• [FILTER]: filter가 만든 모든 결과를 array로 수집한다.
• to_entries, from_entries, with_entries(FILTER): object와 key/value entry array 사이를 변환한다.
• sort_by(FILTER), group_by(FILTER), unique_by(FILTER): array를 기준값으로 정렬, 그룹화, 중복 제거한다.
• add, min, max, length: collection 집계에 사용한다.
• //는 왼쪽 결과가 false 또는 null일 때 오른쪽 default를 사용한다.

printf '%s\n' '{"name":"jq","version":"1.8"}' | jq .
printf '%s\n' '{"name":"jq","version":"1.8"}' | jq -r '.name'
jq '.items[] | .name' data.json

기존 command record:

go env -json | jq .GOAUTH

jq '.users[] | select(.active == true) | {id, name}' users.json
jq '[.items[] | select(.price >= 100)] | sort_by(.price)' catalog.json

user_name='alice'
enabled='true'
jq -n --arg name "$user_name" --argjson enabled "$enabled" \
  '{name: $name, enabled: $enabled}'

jq -s 'add' part-*.json
printf '%s\n' alpha beta gamma | jq -R -s 'split("\n")[:-1]'
jq -n --slurpfile config config.json '$config'

if jq -e '.healthy == true' status.json >/dev/null; then
  echo 'healthy'
else
  echo 'not healthy or invalid input'
fi

-e의 exit code 1은 JSON parse error와 같지 않다. script에서 원인을 구분해야 하면 jq의 실제 exit code와 standard error를 함께 확인한다.

jq 1.7 이상에서는 NUL-delimited output을 사용할 수 있다.

jq --raw-output0 '.files[]' manifest.json |
  while IFS= read -r -d '' file; do
    printf '%s\n' "$file"
  done

• jq에는 일반적인 user-wide config file이 없다. 반복 filter는 -f FILE이나 module로 분리한다.
• NO_COLOR가 비어 있지 않으면 기본 color output을 끈다. -C는 이를 명시적으로 다시 활성화할 수 있다.
• JQ_COLORS는 terminal color 구성을 바꾼다. 자동화에서는 환경별 색상 차이를 피하려고 -M을 명시하는 편이 안전하다.
• module 검색 위치는 -L DIRECTORY로 제어한다. 이 option을 주면 default search list가 대체되므로 필요한 module path를 모두 지정한다.

• 입력이 JSON인지 먼저 확인한다. 일반 text나 log line이면 -R이 필요할 수 있다.
• 여러 JSON document가 연속될 수는 있지만 comma가 빠진 하나의 array로 간주되지는 않는다. 모두 모으려면 -s를 검토한다.
• HTTP 응답을 처리할 때 JSON body 대신 HTML error page가 들어오지 않았는지 status와 content type을 먼저 확인한다.

• 예상한 object가 아니라 string 또는 array가 입력된 경우다. type, keys, .로 중간 구조를 확인한다.
• 값이 없을 수 있다면 optional operator ? 또는 default operator //를 사용하되, 실제 schema 오류를 무조건 숨기지 않는다.

• POSIX shell에서는 jq program 전체를 작은따옴표로 감싼다: jq '.name' file.json.
• PowerShell에서는 단순 filter를 작은따옴표로 감싸고, 복잡한 quoting은 .jq file과 -f 사용을 검토한다.
• shell variable은 jq filter 안에 직접 삽입하지 말고 –arg 또는 –argjson으로 전달한다.

• 이 페이지의 option 설명은 공식 jq 1.8 manual을 기준으로 한다.
• –raw-output0는 jq 1.7에서 추가되었으므로 jq 1.6에서는 사용할 수 없다.
• jq는 number를 내부적으로 IEEE 754 double로 표현할 수 있다. 매우 큰 integer의 정확한 보존이 중요한 workflow에서는 사용 중인 build와 변환 결과를 검증한다.
• Windows native jq.exe를 WSL, MSYS2 또는 Cygwin에서 사용할 때 newline 변환을 피하려면 -b, –binary가 필요할 수 있다.
• 아래 Help는 이 저장소 base environment에 설치된 jq 1.6에서 수집한 원문이며 최신 1.8의 전체 option 목록은 아니다.

jq --help (jq 1.6, local environment)

jq - commandline JSON processor [version 1.6]
 
Usage:	jq [options] <jq filter> [file...]
	jq [options] --args <jq filter> [strings...]
	jq [options] --jsonargs <jq filter> [JSON_TEXTS...]
 
jq is a tool for processing JSON inputs, applying the given filter to
its JSON text inputs and producing the filter's results as JSON on
standard output.
 
The simplest filter is ., which copies jq's input to its output
unmodified (except for formatting, but note that IEEE754 is used
for number representation internally, with all that that implies).
 
For more advanced filters see the jq(1) manpage ("man jq")
and/or https://stedolan.github.io/jq
 
Example:
 
	$ echo '{"foo": 0}' | jq .
	{
		"foo": 0
	}
 
Some of the options include:
  -c               compact instead of pretty-printed output;
  -n               use `null` as the single input value;
  -e               set the exit status code based on the output;
  -s               read (slurp) all inputs into an array; apply filter to it;
  -r               output raw strings, not JSON texts;
  -R               read raw strings, not JSON texts;
  -C               colorize JSON;
  -M               monochrome (don't colorize JSON);
  -S               sort keys of objects on output;
  --tab            use tabs for indentation;
  --arg a v        set variable $a to value <v>;
  --argjson a v    set variable $a to JSON value <v>;
  --slurpfile a f  set variable $a to an array of JSON texts read from <f>;
  --rawfile a f    set variable $a to a string consisting of the contents of <f>;
  --args           remaining arguments are string arguments, not files;
  --jsonargs       remaining arguments are JSON arguments, not files;
  --               terminates argument processing;
 
Named arguments are also available as $ARGS.named[], while
positional arguments are available as $ARGS.positional[].
 
See the manpage for more options.

• curl
• GitHub CLI (gh)
• Go
• jq 1.8 Manual
• Download jq
• jq Releases

• codex:: 2026-08-17 Migrated jq to a language head page and added official installation, jq 1.8 options, filter examples, shell safety, and compatibility guidance while preserving the original command and help record.