curl JSON pretty print(정렬) 방법 4가지 - jq / Python / 브라우저

Q: curl -i와 jq를 파이프로 연결하면 왜 parse error가 발생하나요?

curl -i는 응답 본문뿐만 아니라 HTTP 상태 코드와 헤더 블록을 표준 출력(stdout)의 맨 위에 함께 출력합니다. 파이프(|)로 jq에 넘기면 HTTP/2 200 같은 첫 줄의 헤더 텍스트를 JSON으로 파싱하려고 시도하기 때문에 parse error: Invalid numeric literal 오류가 발생합니다. 헤더를 stderr로 돌리는 curl -sSD /dev/stderr ... | jq . 패턴을 사용해야 합니다.

Q: 한글이나 특수문자가 \uXXXX 형태로 출력될 때 어떻게 해결하나요?

Python json.tool은 기본적으로 비ASCII 문자를 이스케이프합니다. 명령어 뒤에 --no-ensure-ascii 플래그를 추가하면 한글이 원래 문자 그대로 출력됩니다(Python 3.9 이상). jq는 기본적으로 한글을 그대로 출력하지만, 만약 \uXXXX로 나오고 있다면 -a 플래그가 붙어 있지 않은지 확인하세요.

Q: Windows PowerShell에서 curl JSON pretty print를 하려면 어떻게 하나요?

PowerShell 환경에서는 /dev/stderr 장치 파일이 존재하지 않습니다. 따라서 curl.exe -sSD head.txt -o body.json 명령으로 헤더와 본문을 파일로 분리한 뒤 cat head.txt와 jq . body.json을 순차적으로 실행하거나, 본문만 필요하다면 curl.exe -s | jq .를 실행하면 됩니다. (PowerShell 기본 curl은 Invoke-WebRequest의 별칭일 수 있으므로 curl.exe를 명시하는 것이 안전합니다.)

Q: jq가 없는 환경에서 가장 빠르게 JSON을 정렬하는 방법은 무엇인가요?

추가 패키지 설치 권한이 없는 원격 리눅스 서버 등에서는 Python 표준 모듈인 python3 -m json.tool --no-ensure-ascii를 사용하는 것이 가장 빠르고 안전합니다. Node.js가 있다면 node -e 'console.log(JSON.stringify(JSON.parse(require("fs").readFileSync(0, "utf-8")), null, 2))'로도 처리할 수 있습니다.

TL;DR — 한 줄 명령어(원라이너)

jq가 설치되어 있다면 다음 명령어로 바로 끝납니다.

curl -s https://api.example.com/users/1 | jq .

jq가 없는 환경이라면 대부분의 시스템에 기본 설치되어 있는 Python을 사용하면 됩니다.

curl -s https://api.example.com/users/1 | python3 -m json.tool

터미널 대신 브라우저에서 편하게 확인하고 싶다면 curl 결과를 FormatArc JSON 포맷터에 붙여넣기만 하면 됩니다. 별도 설치가 필요 없고 첫 로드 후에는 오프라인에서도 작동합니다. 아래에서는 4가지 방법을 비교하고 어떤 상황에서 무엇을 선택해야 하는지 자세히 다룹니다.

curl 응답이 읽기 어려운 이유

API 동작을 점검할 때 curl을 실행하면 응답 JSON이 한 줄로 길게 반환됩니다.

curl -s https://api.example.com/users/1

{"id":1,"name":"Tanaka","email":"tanaka@example.com","address":{"city":"Tokyo","zip":"100-0001"},"roles":["admin","editor"]}

줄바꿈이나 들여쓰기가 전혀 없기 때문에 계층 구조가 깊어질수록 눈으로 데이터를 파악하기가 거의 불가능해집니다. 이 긴 텍스트를 읽기 쉽게 정렬(pretty print)하는 4가지 방법을 소개합니다.

방법 1: jq로 pretty print(정렬)하기

명령줄에서 JSON을 처리하고 정렬할 때 가장 널리 쓰이는 도구는 jq입니다.

jq 설치 방법

운영체제별 패키지 관리자를 통해 쉽게 설치할 수 있습니다.

# macOS
brew install jq

# Ubuntu / Debian
sudo apt install jq

# Windows (Chocolatey)
choco install jq

기본 사용법

curl의 출력을 파이프(|)로 jq에 넘겨주기만 하면 됩니다.

curl -s https://api.example.com/users/1 | jq .

{
  "id": 1,
  "name": "Tanaka",
  "email": "tanaka@example.com",
  "address": {
    "city": "Tokyo",
    "zip": "100-0001"
  },
  "roles": [
    "admin",
    "editor"
  ]
}

-s 옵션은 curl의 다운로드 진행률 표시(프로그레스 바)를 숨겨서 순수한 JSON 내용만 jq로 전달되도록 만듭니다.

자주 쓰는 필터

jq는 단순 정렬뿐만 아니라 응답에서 원하는 특정 필드만 골라내는 필터 기능도 강력합니다.

특정 키의 값만 가져올 때는 다음과 같이 작성합니다.

curl -s https://api.example.com/users/1 | jq '.name'

"Tanaka"

중첩된 객체의 키에는 점(.)으로 접근합니다.

curl -s https://api.example.com/users/1 | jq '.address.city'

"Tokyo"

배열 안에 있는 모든 요소에서 특정 필드를 추출할 때는 [] 구문을 사용합니다.

curl -s https://api.example.com/users | jq '.[].name'

"Tanaka"
"Suzuki"
"Sato"

조건에 맞는 데이터만 필터링할 때는 select를 사용합니다.

curl -s https://api.example.com/users | jq '.[] | select(.roles[] == "admin")'

배열 응답을 추출해 문서나 이슈에 붙여넣을 마크다운 표로 변환하고 싶다면, jq로 배열을 잘라낸 뒤 CSV를 거쳐 표 형태로 만드는 파이프라인 워크플로를 구축할 수도 있습니다. 자세한 방법은 API 응답 JSON을 마크다운 표로 변환하기를 참고하세요.

curl -i로 응답 헤더와 JSON을 동시에 정렬하기

앞서 살펴본 -s 옵션 예제는 응답 본문(body)을 제외한 모든 정보를 버립니다. 하지만 API 디버깅 중에는 HTTP 상태 코드나 응답 헤더(header)를 본문과 함께 확인해야 할 때가 많습니다. 이때 curl -i를 떠올리게 되지만, curl -i | jq .는 무조건 실패합니다. 스트림 맨 위에 출력되는 HTTP 헤더 블록이 유효한 JSON이 아니기 때문입니다.

curl -is https://api.example.com/users/1 | jq .
# parse error: Invalid numeric literal at line 1, column 9

헤더는 터미널에 그대로 표시하면서 jq에는 순수한 JSON 본문만 전달하는 분리 처리가 필요합니다.

스트림 분리: 헤더는 stderr, 본문은 stdout으로

curl -D <파일> 옵션은 응답 헤더를 지정한 대상에 기록합니다. 여기에 /dev/stderr를 지정하면 헤더는 표준 오류(stderr)로 터미널 화면에 즉시 출력되고, 표준 출력(stdout)에는 jq가 처리할 수 있는 순수한 JSON 본문만 남게 됩니다.

curl -sSD /dev/stderr https://api.example.com/users/1 | jq .

HTTP/2 200
content-type: application/json
cache-control: no-store
date: Mon, 19 May 2026 09:30:00 GMT

{
  "id": 1,
  "name": "Tanaka",
  ...
}

헤더는 터미널 화면에 표시되지만 파이프로는 넘어가지 않으므로 jq는 온전한 JSON만 받아서 깔끔하게 정렬합니다. Windows PowerShell 환경에서는 /dev/stderr가 지원되지 않으므로 헤더를 별도 파일로 저장한 뒤 확인하는 패턴을 사용합니다.

파일로 분리: 헤더와 본문을 따로 저장

실패한 요청을 분석하거나 버그 리포트에 첨부하기 위해 헤더와 본문을 모두 파일로 보관하고 싶다면 -D와 -o 옵션을 함께 사용합니다.

curl -sSD head.txt -o body.json https://api.example.com/users/1
cat head.txt
jq . body.json

이 방식은 macOS, Linux, Windows 등 모든 셸 환경에서 동일하게 동작합니다. 나중에 헤더에서 특정 값을 grep으로 찾거나 로그 파일로 보관할 때 유용합니다.

영구적인 셸 alias로 만들기

매번 긴 옵션을 입력하는 대신 셸 설정 파일(~/.bashrc 또는 ~/.zshrc)에 단축 명령어를 등록해 둘 수 있습니다.

alias curl-json='curl -sSD /dev/stderr'
curl-json-format() { curl-json "$@" | jq .; }

이렇게 설정해 두면 curl-json-format https://api.example.com/users/1 명령어 하나로 헤더 확인과 본문 JSON 정렬을 한 번에 끝낼 수 있습니다.

curl 7.82 이후의 `--json` 단축 플래그(요청 전송 시)

응답을 정렬하는 것과 반대로 JSON 데이터를 API 서버로 전송해야 하는 상황도 있습니다. curl 7.82(2022년 3월 릴리스)부터는 --json 단축 플래그가 지원되어 Content-Type: application/json, Accept: application/json, --data 설정을 단 하나의 플래그로 묶어서 지정할 수 있습니다.

curl --json '{"name":"alice"}' https://api.example.com/users

이 플래그 자체는 요청을 보내는 용도이므로 응답을 정렬하려면 앞서 소개한 curl-json-format이나 jq 파이프와 조합해서 사용하면 REST API 요청과 응답 디버깅을 간결하게 구성할 수 있습니다.

체크리스트: curl 응답이 유효한 JSON인지 확인하기

jq나 Python 등의 포맷터로 응답을 넘기기 전에 두 가지를 점검해야 합니다. 서버가 응답을 JSON으로 명시했는지, 그리고 본문 자체가 문법적으로 올바른 형식인지입니다. JSON 데이터 교환 표준은 RFC 8259 (STD 90)새 탭에서 열립니다에 정의되어 있으며, 문법 요약은 json.org새 탭에서 열립니다에서 확인할 수 있습니다.

Content-Type 헤더가 application/json인지 확인합니다. RFC 8259는 JSON의 공식 미디어 타입으로 application/json을 등록하고 있습니다. curl -i나 앞서 소개한 curl -sSD /dev/stderr로 헤더를 확인했을 때 text/html 등이 반환된다면 JSON API 대신 에러 페이지, 로그인 리다이렉트 화면, 프록시 오류 HTML이 돌아온 것일 가능성이 높습니다.
본문이 정형화된(well-formed) JSON인지 확인합니다. JSON 문서는 단일 값(객체, 배열, 문자열, 숫자, 또는 true/false/null)이어야 합니다(RFC 8259 2절). 객체의 키는 반드시 큰따옴표(")로 감싸야 하며 작은따옴표나 마지막 요소 뒤의 후행 쉼표(trailing comma)는 허용되지 않습니다. 또한 RFC 8259 8.1절에 따라 시스템 간 교환되는 JSON은 UTF-8로 인코딩되어야 합니다.
파서가 오류 없이 해석하는지 확인합니다. jq .나 python3 -m json.tool이 정렬된 결과 대신 파싱 에러를 던진다면 헤더 값과 상관없이 해당 본문은 유효한 JSON이 아닙니다. //나 /* */ 주석은 표준 JSON에 포함되지 않으므로, 주석이 들어 있는 파일은 엄밀히 JSON이 아니라 JSONC 또는 JSON5 형식입니다.

방법 2: Python json.tool로 정렬하기

서버나 로컬 환경에 Python이 설치되어 있다면 별도의 도구를 설치할 필요가 없습니다. Python 표준 라이브러리에 포함된 json.tool 모듈을 사용하면 됩니다.

curl -s https://api.example.com/users/1 | python3 -m json.tool

{
    "id": 1,
    "name": "Tanaka",
    "email": "tanaka@example.com",
    "address": {
        "city": "Tokyo",
        "zip": "100-0001"
    },
    "roles": [
        "admin",
        "editor"
    ]
}

jq처럼 특정 키를 추출하는 필터링 기능은 없지만, 응답을 들여쓰기하여 가독성을 높이는 용도로는 충분합니다. Python 2만 있는 레거시 환경이라면 python 명령어로 대체할 수 있습니다.

비ASCII 문자(한글 등)가 기본적으로 \uXXXX로 이스케이프되는 문제

json.tool을 사용할 때 주의할 점이 있습니다. 기본 설정 상태에서는 한글이나 악센트 기호가 포함된 비ASCII 문자를 \uXXXX 형태의 유니코드 이스케이프 시퀀스로 변환해 출력합니다.

echo '{"city":"Bogotá","msg":"情報","p":"informação"}' | python3 -m json.tool

{
    "city": "Bogot\u00e1",
    "msg": "\u60c5\u5831",
    "p": "informa\u00e7\u00e3o"
}

이것은 버그가 아니라 JSON 표준 사양에 따른 정상 동작입니다. JSON 문자열은 기본 다국어 평면(BMP)의 문자를 역슬래시(\) + u + 4자리 16진수로 표현할 수 있도록 규정되어 있습니다(RFC 8259 7절새 탭에서 열립니다). 하지만 한글이나 다국어 데이터를 터미널에서 눈으로 직접 읽으려고 할 때는 가독성이 크게 떨어집니다.

원래 글자 그대로 출력하려면 --no-ensure-ascii 옵션을 추가합니다. 이 플래그는 Python 3.9에 추가되었습니다(Python 공식 문서새 탭에서 열립니다).

echo '{"city":"Bogotá","msg":"情報","p":"informação"}' | python3 -m json.tool --no-ensure-ascii

{
    "city": "Bogotá",
    "msg": "情報",
    "p": "informação"
}

반대로 jq는 기본 동작이 정반대입니다. 기본적으로 비ASCII 문자를 UTF-8 원본 그대로 출력하며, -a(--ascii-output) 옵션을 붙여야 \uXXXX로 이스케이프합니다(jq 공식 매뉴얼새 탭에서 열립니다).

echo '{"city":"Bogotá","msg":"情報","p":"informação"}' | jq -a .

{
  "city": "Bogot\u00e1",
  "msg": "\u60c5\u5831",
  "p": "informa\u00e7\u00e3o"
}

이 실측 결과(Python 3.14.6 / jq 1.7.1)는 저장소 내 scripts/benchmarks/json-tool-non-ascii/에 검증 데이터로 보관되어 있습니다.

방법 3: formatarc CLI로 정렬하기

설치와 사용법

Node.js 환경을 사용 중이라면 npx를 통해 설치 과정 없이 즉시 실행할 수 있습니다.

curl -s https://api.example.com/users/1 | npx formatarc json-format

{
  "id": 1,
  "name": "Tanaka",
  "email": "tanaka@example.com",
  "address": {
    "city": "Tokyo",
    "zip": "100-0001"
  },
  "roles": [
    "admin",
    "editor"
  ]
}

자주 사용하는 도구라면 전역(global)으로 설치해 npx 시작 지연 없이 빠르게 실행할 수도 있습니다.

npm install -g formatarc
curl -s https://api.example.com/users/1 | formatarc json-format

YAML / CSV 변환 파이프라인 연계

formatarc는 JSON 정렬뿐만 아니라 파이프라인에서 바로 YAML이나 CSV 형식으로 변환하는 기능도 제공합니다.

curl -s https://api.example.com/users/1 | npx formatarc json-to-yaml

id: 1
name: Tanaka
email: tanaka@example.com
address:
  city: Tokyo
  zip: "100-0001"
roles:
  - admin
  - editor

API 응답 데이터를 받아 즉시 설정 파일(YAML)이나 스프레드시트용 데이터(CSV)로 변환해야 할 때 파이프 하나로 연계할 수 있어 유용합니다. 자세한 CLI 사용법은 formatarc CLI 도입 가이드를 참고하세요.

방법 4: 브라우저(FormatArc)에서 정렬하기

FormatArc JSON 포맷터 사용법

터미널 명령어 대신 그래픽 인터페이스에서 편하게 작업하고 싶다면 웹 브라우저를 이용하는 방법이 있습니다. curl 출력을 복사해 FormatArc JSON 포맷터에 붙여넣으면 원클릭으로 정렬됩니다.

사용 절차는 간단합니다.

터미널의 curl 응답을 복사합니다.
FormatArc JSON 포맷터를 엽니다.
왼쪽 입력창에 붙여넣습니다.
"Format" 버튼을 누릅니다.

정렬된 결과는 클릭 한 번으로 복사할 수 있으며, 필요하다면 도구 화면에서 바로 YAML이나 CSV로 변환할 수도 있습니다.

온라인 도구를 사용할 때 한 가지 확인해야 할 점은 보안입니다. curl 응답에는 Authorization 토큰, 세션 키, 사용자 개인정보 등 민감한 데이터가 포함되는 경우가 많습니다. 일반적인 온라인 변환기 중에는 입력 데이터를 서버로 전송하는 곳이 적지 않습니다. FormatArc는 모든 변환 처리를 사용자의 브라우저 내에서만 실행하므로 데이터가 외부 서버로 전송되지 않아 안심하고 사용할 수 있습니다. 온라인 도구의 안전성을 점검하는 기준은 온라인 변환 사이트 보안 검증을 참고하세요.

구문 오류가 발생한 경우

응답 JSON에 문법 오류가 있으면 정렬이 실패합니다. 따옴표 누락, 후행 쉼표, 이스케이프되지 않은 제어 문자 등이 대표적인 원인입니다. 자주 발생하는 원인과 해결 방법은 JSON 파싱 오류 해결 방법을 참고하세요.

만약 API 응답에 //나 /* */ 주석이 포함되어 있어 jq나 json.tool 파싱에 실패한다면, 해당 데이터는 표준 JSON이 아니라 JSONC나 JSON5 형식일 가능성이 높습니다. 주석을 제거하거나 해당 포맷을 지원하는 파서를 거쳐야 정상적으로 읽을 수 있습니다. 주석 작성과 대안에 대한 자세한 내용은 JSON 주석 작성 방법을 참고하세요.

웹 브라우저 탭에서 JSON URL을 열었을 때 자동으로 정렬되도록 구성하고 싶다면 크롬 확장 프로그램을 활용하는 것도 대안이 됩니다. 추천 확장 프로그램 비교는 크롬 JSON 확장 프로그램 비교를 참고하세요.

4가지 방법 비교와 선택 기준

방법	별도 설치	필터링 기능	추천 상황
jq	필요	강력함	API를 매일 다루는 백엔드·데브옵스 개발자
Python json.tool	불필요 (Python 환경)	없음	추가 도구 설치 없이 빠르게 정렬할 때
formatarc CLI	npx 즉시 실행 가능	없음 (변환 지원)	JSON 정렬과 함께 YAML/CSV 변환이 필요할 때
브라우저 (FormatArc)	불필요	없음	터미널 작업이 번거롭거나 시각적으로 확인하고 싶을 때

평소 터미널 작업에서는 jq를 기본으로 사용하고, jq가 없는 서버에서는 python3 -m json.tool --no-ensure-ascii를 활용하며, 다른 포맷으로의 변환이나 안전한 시각적 확인이 필요할 때는 FormatArc를 병행하는 조합이 가장 효율적입니다.

자주 묻는 질문

curl -i와 jq를 파이프로 연결하면 왜 parse error가 발생하나요?

curl -i는 응답 본문뿐만 아니라 HTTP 상태 코드와 헤더 블록을 표준 출력(stdout)의 맨 위에 함께 출력합니다. 파이프(|)로 jq에 넘기면 HTTP/2 200 같은 첫 줄의 헤더 텍스트를 JSON으로 파싱하려고 시도하기 때문에 parse error: Invalid numeric literal 오류가 발생합니다. 헤더를 stderr로 돌리는 curl -sSD /dev/stderr ... | jq . 패턴을 사용해야 합니다.

한글이나 특수문자가 \uXXXX 형태로 출력될 때 어떻게 해결하나요?

Python json.tool은 기본적으로 비ASCII 문자를 이스케이프합니다. 명령어 뒤에 --no-ensure-ascii 플래그를 추가하면 한글이 원래 문자 그대로 출력됩니다(Python 3.9 이상). jq는 기본적으로 한글을 그대로 출력하지만, 만약 \uXXXX로 나오고 있다면 -a 플래그가 붙어 있지 않은지 확인하세요.

Windows PowerShell에서 curl JSON pretty print를 하려면 어떻게 하나요?

PowerShell 환경에서는 /dev/stderr 장치 파일이 존재하지 않습니다. 따라서 curl.exe -sSD head.txt -o body.json <URL> 명령으로 헤더와 본문을 파일로 분리한 뒤 cat head.txt와 jq . body.json을 순차적으로 실행하거나, 본문만 필요하다면 curl.exe -s <URL> | jq .를 실행하면 됩니다. (PowerShell 기본 curl은 Invoke-WebRequest의 별칭일 수 있으므로 curl.exe를 명시하는 것이 안전합니다.)

jq가 없는 환경에서 가장 빠르게 JSON을 정렬하는 방법은 무엇인가요?

추가 패키지 설치 권한이 없는 원격 리눅스 서버 등에서는 Python 표준 모듈인 python3 -m json.tool --no-ensure-ascii를 사용하는 것이 가장 빠르고 안전합니다. Node.js가 있다면 node -e 'console.log(JSON.stringify(JSON.parse(require("fs").readFileSync(0, "utf-8")), null, 2))'로도 처리할 수 있습니다.

curl 응답에 주석(//)이 포함되어 파싱 오류가 날 때는 어떻게 하나요?

RFC 8259 표준 JSON은 주석을 지원하지 않습니다. 응답에 주석이 섞여 있다면 JSONC나 JSON5 형식입니다. FormatArc JSON 포맷터에 붙여넣으면 주석과 후행 쉼표를 감지하여 유효한 표준 JSON으로 정리할 수 있습니다.

정리

curl로 가져온 JSON을 정렬하는 4가지 방법을 살펴보았습니다. jq는 필터링과 데이터 추출까지 가능한 가장 강력한 도구이며, curl -sSD /dev/stderr | jq . 패턴을 활용하면 HTTP 헤더를 확인하면서 본문 JSON만 깔끔하게 정렬할 수 있습니다. 별도 도구 설치가 어려운 환경에서는 Python의 json.tool을 활용하고, 브라우저에서 안전하게 확인하거나 다른 데이터 형식으로 변환하고 싶다면 FormatArc JSON 포맷터를 활용해 보세요.

TL;DR — 한 줄 명령어(원라이너)

curl 응답이 읽기 어려운 이유

방법 1: jq로 pretty print(정렬)하기

jq 설치 방법

기본 사용법

자주 쓰는 필터

curl -i로 응답 헤더와 JSON을 동시에 정렬하기

스트림 분리: 헤더는 stderr, 본문은 stdout으로

파일로 분리: 헤더와 본문을 따로 저장

영구적인 셸 alias로 만들기

curl 7.82 이후의 --json 단축 플래그(요청 전송 시)

체크리스트: curl 응답이 유효한 JSON인지 확인하기

방법 2: Python json.tool로 정렬하기

비ASCII 문자(한글 등)가 기본적으로 \uXXXX로 이스케이프되는 문제

방법 3: formatarc CLI로 정렬하기

설치와 사용법

YAML / CSV 변환 파이프라인 연계

방법 4: 브라우저(FormatArc)에서 정렬하기

FormatArc JSON 포맷터 사용법

구문 오류가 발생한 경우

4가지 방법 비교와 선택 기준

자주 묻는 질문

curl -i와 jq를 파이프로 연결하면 왜 parse error가 발생하나요?

한글이나 특수문자가 \uXXXX 형태로 출력될 때 어떻게 해결하나요?

Windows PowerShell에서 curl JSON pretty print를 하려면 어떻게 하나요?

jq가 없는 환경에서 가장 빠르게 JSON을 정렬하는 방법은 무엇인가요?

curl 응답에 주석(//)이 포함되어 파싱 오류가 날 때는 어떻게 하나요?

정리

curl 7.82 이후의 `--json` 단축 플래그(요청 전송 시)