헤드리스 브라우저는 창이 안 뜨는 브라우저입니다. 화면(UI)이 눈에 보이지 않을 뿐, 페이지를 읽고 그리고 자바스크립트를 실행하는 일은 일반 브라우저와 같습니다. 자동화·크롤링·캡처 이야기에 자주 나오는 말이라, 무엇이고 어떻게 쓰고 어디서 막히는지를 공식 문서와 예시 실행 결과로 정리했습니다.
‘머리’가 화면이다
이름이 좀 이상합니다. 여기서 머리(head)는 화면을 뜻합니다. 화면이 없는 상태로 돈다는 뜻입니다. Chrome 공식 문서는 헤드리스 모드를 “눈에 보이는 UI 없이, 사람이 지켜보지 않는 환경에서 브라우저를 돌리는 방식”으로 설명합니다.
중요한 건 화면이 없어도 브라우저는 할 일을 다 한다는 점입니다. HTML을 읽고, CSS를 적용해 배치를 계산하고, 자바스크립트를 실행합니다. 마지막에 사람 눈앞에 띄우는 단계만 건너뜁니다. 같은 문서에 따르면 Chrome 112부터는 창을 ‘만들되 보여주지 않는’ 방식으로 바뀌어, 평소 쓰는 Chrome과 같은 코드를 공유합니다.
어디에 쓰나
- 화면 캡처 — 페이지를 그려서 이미지 파일로 저장합니다. 사람이 볼 필요가 없으니 창을 띄울 이유도 없습니다.
- 내용 가져오기 — 자바스크립트로 그려지는 페이지는 주소만 요청해서는 내용이 안 나옵니다. 브라우저가 실제로 실행해 줘야 보입니다.
- 자동 시험 — 버튼을 누르고 결과를 확인하는 일을 사람 대신 반복합니다.
- PDF 만들기 — 웹 페이지를 인쇄 형식으로 저장하는 일도 같은 방식으로 합니다.
이미 설치돼 있다: 명령 한 줄로 캡처하기
따로 뭘 받을 필요가 없는 경우가 많습니다. 크롬에 이미 들어 있습니다. 실행할 때 옵션 하나만 붙이면 됩니다. 맥 기준 예시입니다.
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--headless --screenshot=out.png --window-size=1080,1080 \
file:///내-폴더/card.html--headless가 창을 안 띄우라는 뜻이고, --screenshot이 찍어서 파일로 저장하라는 뜻이며, --window-size가 찍을 화면의 가로,세로 크기입니다. 주소 대신 내 컴퓨터의 파일(file:///)도 넣을 수 있습니다. Chrome 개발자 블로그의 headless 소개에도 --screenshot, --print-to-pdf, --window-size 조합이 예시로 나옵니다.
예시 실행 결과
설명만 읽으면 감이 안 오는 부분이라, 맥(Chrome 154.0.8037.98)에서 아래 시험을 실행한 결과를 표로 정리했습니다. 시험용 페이지는 제목 한 줄과 문단 하나로 되어 있고, 문단은 처음에 “처음”이라고 적혀 있다가 자바스크립트가 2초 뒤에 “2초 뒤 채워진 글”로 바꿉니다. 한글 제목에는 숫자도 섞었습니다.
| 실행 방식 | 결과 | 알 수 있는 것 |
|---|---|---|
--headless --screenshot --window-size=1080,600 | 1080×600 PNG가 약 1.5초 만에 저장됨(약 14KB). 글자는 “처음” | 한글이 깨지지 않고 찍힘. 그러나 2초 뒤 바뀌는 내용은 못 담음 |
위 옵션에 --virtual-time-budget=5000 추가 | 같은 크기 PNG. 글자는 “2초 뒤 채워진 글” | 기다리는 옵션을 주면 나중에 채워지는 내용까지 찍힘 |
--headless --dump-dom(캡처 없이 DOM 출력) | HTML이 터미널에 출력됨. 문단은 “처음” | 캡처가 아니라 ‘그린 뒤의 HTML’을 받을 때도 같은 기다림 문제가 생김 |
두 번째 방식의 명령은 이렇습니다.
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--headless --screenshot=out.png --window-size=1080,600 \
--virtual-time-budget=5000 file:///내-폴더/card.html이 시험에서 눈에 띈 점이 하나 더 있습니다. 실행 중 화면 표시 장치와 관련된 오류처럼 보이는 로그 줄이 여러 줄 출력됐지만, 이미지 파일은 정상적으로 저장됐습니다. 로그에 ‘ERROR’가 보여도 결과 파일을 열어 보기 전에는 실패라고 단정하지 않는 편이 좋습니다. 반대로 로그가 조용해도 결과가 비어 있을 수 있으니, 결국 저장된 파일을 열어서 확인하는 것이 가장 확실합니다. 다만 위 시간·용량은 이 한 대의 맥에서 한 번 잰 값이며, 컴퓨터와 페이지에 따라 달라집니다. --virtual-time-budget은 위에 인용한 Chrome 문서 페이지에는 설명이 없는 옵션이므로, 버전에 따라 동작이 달라질 수 있다는 점을 염두에 두세요.
헤드리스에도 두 종류가 있다
예전에는 헤드리스가 일반 Chrome과 따로 만든 별개의 구현이었습니다. 공식 문서에 따르면 지금의 헤드리스는 일반 Chrome과 코드를 공유하는 방식으로 통합됐고, 옛 방식은 Chrome 132.0.6793.0부터 chrome-headless-shell이라는 별도 실행 파일로만 받을 수 있습니다. 두 가지는 이렇게 나뉩니다.
| 구분 | 특징 | 어울리는 일 |
|---|---|---|
새 헤드리스(--headless) | 일반 Chrome과 같은 코드를 씀. 실제 Chrome에 가까운 동작 | 웹 앱 시험, 확장 프로그램 시험처럼 ‘진짜 Chrome처럼’ 동작해야 하는 일 |
chrome-headless-shell(옛 방식) | 더 가볍고 의존 요소가 적음. Puppeteer 문서는 일반 Chrome과 동작이 완전히 같지는 않다고 안내 | 화면 캡처, 대량 수집처럼 속도와 가벼움이 중요한 일 |
Puppeteer 같은 자동화 라이브러리에서는 headless: true가 새 방식(기본값), headless: 'shell'이 chrome-headless-shell, headless: false가 창이 보이는 일반 모드입니다. 처음 시작한다면 기본값으로 충분하고, 속도가 문제가 될 때 옮겨 가면 됩니다.
알아둘 것
보이지 않으니 뭐가 잘못됐는지 알기 어렵습니다. 페이지가 안 뜨거나 글자가 깨져도 그냥 이상한 이미지가 하나 나올 뿐입니다. 그래서 결과 파일을 실제로 열어 봐야 합니다.
폰트는 그 컴퓨터에 있는 것만 씁니다. 위 시험은 한글 폰트가 깔린 맥에서 돌려서 글자가 정상으로 나왔습니다. 한글 폰트가 설치되지 않은 서버에서 돌리면 글자가 네모로 나올 수 있으니, 서버에 쓸 폰트를 따로 설치해야 합니다.
기다려야 할 때가 있습니다. 위 표처럼 내용을 나중에 불러오는 페이지는 찍는 순간 비어 있을 수 있습니다. 단순 명령 옵션으로 부족하면 Puppeteer 같은 도구의 대기 기능(특정 요소가 나타날 때까지 기다리기)을 쓰는 편이 안정적입니다.
남의 사이트에는 규칙이 있습니다. 창이 보이지 않는다고 접속 기록이 사라지지는 않습니다. 이용 약관과 로봇 접근 규칙(robots.txt), 요청 속도를 지켜야 하고, 로그인·결제·게시처럼 사람이 확인해야 하는 행동까지 무조건 자동화하는 것은 피하는 편이 좋습니다. 읽기와 확인부터 작은 범위로 시작하세요.
처음 해 보는 사람을 위한 순서
| 단계 | 할 일 | 확인할 것 |
|---|---|---|
| 1. 대상 정하기 | 내 컴퓨터의 간단한 HTML 파일 하나 | 제목과 글자가 들어 있는 짧은 페이지면 충분 |
| 2. 캡처 실행 | 위 명령에서 파일 주소와 저장 이름만 바꿔 실행 | 저장된 PNG가 생겼는지, 크기가 --window-size와 같은지 |
| 3. 눈으로 확인 | 생성된 이미지를 열어 봄 | 한글이 깨졌는지, 내용이 비어 있지 않은지 |
| 4. 기다림 시험 | 2~3초 뒤 내용이 바뀌는 페이지로 반복 | ‘처음’ 상태로 찍히면 대기 옵션이나 도구의 대기 기능 사용 |
| 5. 범위 넓히기 | 외부 사이트는 이용 규칙을 확인한 뒤 읽기부터 | 요청 횟수와 간격을 작게 유지 |
정리하면
헤드리스 브라우저는 특별한 프로그램이 아니라 브라우저를 쓰는 한 가지 방식입니다. 사람이 볼 필요가 없는 일에 창을 띄우지 않을 뿐입니다. 이미 설치된 Chrome으로 명령 한 줄이면 시험해 볼 수 있고, 기다림·폰트·사이트 규칙 세 가지만 조심하면 대부분의 첫 시도가 풀립니다. 속도가 중요해지면 chrome-headless-shell을, 실제 Chrome과 같은 동작이 중요하면 기본 헤드리스를 고르면 됩니다.
다른 자동화 도구는 헤드리스를 어떻게 다루나
Playwright 공식 문서에 따르면 헤드리스로 실행할 때 기본으로 쓰는 것은 ‘chromium headless shell’이며, 화면이 있는 모드에서 쓰는 일반 Chromium과는 따로 배포됩니다. 시험을 헤드리스로만 돌리는 CI 환경이라면 설치할 때 --only-shell 옵션으로 전체 Chromium 내려받기를 건너뛸 수 있다고 안내합니다. 반대로 설정에서 ‘chromium’ 채널을 고르면 새 헤드리스 모드를 쓰게 되고, 문서는 이를 Chrome 문서가 설명한 “진짜 Chrome 브라우저”라고 인용합니다. 이때는 --no-shell로 headless shell 내려받기를 건너뛸 수 있습니다.
또한 Google Chrome과 Microsoft Edge는 새 헤드리스 모드를 쓰므로 일반 모드에 더 가깝고, Playwright 기본값인 headless shell과는 동작이 다를 수 있다고 경고합니다. 앞에서 설명한 ‘두 종류의 헤드리스’가 도구 설정에서는 이렇게 이름을 바꿔 나타납니다.
| 도구 | 가벼운 쪽(옛 방식) | 실제 Chrome에 가까운 쪽(새 방식) |
|---|---|---|
| Chrome 명령줄 | chrome-headless-shell 별도 실행 파일 | --headless |
| Puppeteer | headless: 'shell' | headless: true(기본값) |
| Playwright | 기본값(chromium headless shell) | ‘chromium’ 채널을 지정하거나 Chrome·Edge 사용 |
도구를 고르는 기준
- 결과가 실제 사용자 화면과 같아야 할 때 — 새 헤드리스처럼 일반 브라우저에 가까운 쪽을 고릅니다. 같은 코드로 만든 화면이라도 구현이 다르면 미세하게 달라질 수 있습니다.
- 속도와 설치 용량이 중요할 때 — headless shell처럼 가벼운 쪽을 고릅니다. 다만 일반 Chrome과 동작이 완전히 같지는 않다는 도구 문서의 안내를 염두에 둡니다.
- 한 번만 캡처할 때 — 이미 설치된 Chrome의 명령줄 옵션으로 충분합니다.
- 대기와 반복이 필요할 때 — 특정 요소가 나타날 때까지 기다리는 기능이 있는 자동화 라이브러리를 씁니다.
어느 쪽을 고르든 기본 원칙은 같습니다. 결과 파일을 열어 눈으로 확인하고, 도구 버전을 기록해 두고, 버전이 바뀌면 같은 입력으로 다시 비교합니다. 헤드리스 구현은 버전에 따라 이름과 기본값이 바뀌어 왔기 때문에, 한 번 정해 둔 설정도 업그레이드 뒤에는 다시 확인해야 합니다.
업데이트
이 글은 Chrome for Developers 문서(최종 수정 2024-10-21), Chrome 개발자 블로그의 headless 소개, Puppeteer 가이드, Playwright 문서(2026년 10월 18일 기준)의 내용을 바탕으로 합니다. 브라우저 버전과 옵션은 바뀔 수 있으므로 실제 적용 전에는 아래 공식 자료의 최신 안내를 보세요.
확인 자료
- Chrome for Developers: Chrome Headless mode (열어 본 날: 2026-10-18)
- Chrome for Developers 블로그: chrome-headless-shell (열어 본 날: 2026-10-18)
- Puppeteer: Headless modes (열어 본 날: 2026-10-09)
- Playwright: Browsers (열어 본 날: 2026-10-18)