[매뉴얼] Ubuntu 26.04.1 LTS - wkhtmltopdf 설치 및 한글 폰트 설정 가이드

1. 개요

Ubuntu 26.04(Resolute) 저장소에서는 wkhtmltopdf 개발 프로젝트 중단(Deprecated)으로 인해 공식 apt 기본 패키지 목록에서 제외되었습니다. 따라서 의존성 패키지와 한글 폰트(fonts-nanum)를 우선 설치한 뒤, 호환 패키지(.deb)를 다운로드하여 직접 설치해야 합니다.

2. 사전 준비 및 의존성 설치

wkhtmltopdf 실행에 필요한 그래픽 및 렌더링 라이브러리와 한글 폰트 패키지를 설치합니다.

Bash

 

# 1. 패키지 목록 업데이트 및 의존성 라이브러리/한글 폰트 설치
apt update
apt install -y fonts-nanum xfonts-75dpi xfonts-base libjpeg-turbo8 libx11-6 libxcb1 libxext6 libxrender1

3. wkhtmltopdf 패키지 다운로드 및 설치

공식 릴리즈 가속 바이너리 패키지를 다운로드하여 설치합니다.

Bash

 

# 1. 패키지 다운로드 (Jammy 호환 패키지)
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb

# 2. 패키지 설치
dpkg -i wkhtmltox_0.12.6.1-2.jammy_amd64.deb

# 3. 누락된 의존성(fontconfig 등) 자동 교정 및 완성
apt install -f -y

# 4. 임시 설치 파일 삭제
rm -f wkhtmltox_0.12.6.1-2.jammy_amd64.deb

4. 설치 확인 및 검증 테스트

4.1 버전 확인

이진 실행 파일 경로 및 버전을 확인합니다.

Bash

 

wkhtmltopdf --version

정상 출력 예시: wkhtmltopdf 0.12.6.1 (with patched qt)

4.2 한글 렌더링 및 PDF 변환 테스트

한글 웹사이트 접속 및 PDF 생성이 정상적으로 수행되는지 검증합니다.

Bash

 

# 네이버 메인 페이지 PDF 생성 테스트
wkhtmltopdf --page-size A4 https://www.naver.com /tmp/naver_test.pdf

4.3 생성 결과물 확인

/tmp/naver_test.pdf 파일이 생성되었는지 확인하고 한글 깨짐(네모 □□□ 현상)이 없는지 검수합니다.

5. 트러블슈팅 및 참고사항

5.1 한글 폰트 수동 설치 불필요

과거 리눅스 환경처럼 NanumFont_TTF.zip을 내려받아 /usr/share/fonts/에 수동 압축해제할 필요가 없습니다. apt install fonts-nanum 구문으로 시스템 공식 경로(/usr/share/fonts/truetype/nanum)에 정식 등록 및 캐시 자동 갱신이 처리됩니다.

5.2 X Server 커넥션 에러 시 (headless 지원)

만약 디스플레이 설정 관련 오류(cannot connect to X server)가 발생할 경우, 가상 디스플레이 버퍼 패키지를 추가 설치하여 실행할 수 있습니다.

Bash

 

# Xvfb 설치 (필요시)
apt install -y xvfb

# CLI/PHP 단에서 실행 시
xvfb-run wkhtmltopdf [URL/HTML파일] [출력파일.pdf]