Ubuntu에 WKHTMLtoPDF 설치 방법 (단계별 가이드)

Source: Dev.to

WKHTMLtoPDF란?

WKHTMLtoPDF는 HTML 페이지를 PDF 문서로 변환하는 커맨드‑라인 도구입니다. 다음과 같은 환경에서 널리 사용됩니다:

• Laravel 애플리케이션
• PHP 프로젝트
• Node.js 백‑엔드
• 서버‑사이드 PDF 생성
• 자동화 보고 시스템

공식 빌드는 WKHTMLtoPDF 웹사이트에서 다운로드할 수 있습니다.

Ubuntu에서 WKHTMLtoPDF를 사용하는 이유

Ubuntu 서버는 웹 호스팅 및 백엔드 애플리케이션에 흔히 사용됩니다. Ubuntu에 WKHTMLtoPDF를 설치하면 다음을 수행할 수 있습니다:

• 청구서를 자동으로 생성
• PDF 형식의 보고서 작성
• 동적 웹 페이지를 다운로드 가능한 PDF로 변환
• 문서 워크플로우 자동화

설치 단계

Step 1: Ubuntu 시스템 업데이트

sudo apt update && sudo apt upgrade -y

이 명령은 모든 의존성을 최신 상태로 유지합니다.

Step 2: 필수 의존성 설치

sudo apt install -y fontconfig libxrender1 libxext6 xfonts-base xfonts-75dpi

위 라이브러리는 올바른 폰트 렌더링 및 디스플레이 지원을 보장합니다.

Step 3: Ubuntu용 WKHTMLtoPDF 다운로드

기본 Ubuntu 저장소에 있는 패키지는 오래될 수 있으므로, 공식 .deb 패키지를 설치하는 것이 권장됩니다.

wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.focal_amd64.deb
sudo dpkg -i wkhtmltox_0.12.6-1.focal_amd64.deb

의존성 오류가 발생하면 다음으로 해결합니다:

sudo apt --fix-broken install

설치 확인:

wkhtmltopdf --version

설치된 버전 번호가 표시되어야 합니다.

Step 4: HTML → PDF 변환 테스트

wkhtmltopdf https://example.com output.pdf

PDF가 정상적으로 생성되면 설치가 완료된 것입니다.

흔히 발생하는 설치 오류 및 해결 방법

• WKHTMLtoPDF를 찾을 수 없음

  which wkhtmltopdf

  명령이 경로를 반환하지 않으면 패키지를 다시 설치합니다.

• 필요한 공유 라이브러리 누락

  sudo apt install -f

  누락된 의존성을 자동으로 설치합니다.

• 폰트가 제대로 렌더링되지 않음

  sudo apt install ttf-mscorefonts-installer

프로덕션 서버를 위한 모범 사례

• 항상 공식 안정 버전을 사용합니다.
• 안정성을 위해 snap 설치보다 .deb 패키지를 선호합니다.
• 필수 의존성을 최신 상태로 유지합니다.
• Laravel 프로젝트에서는 barryvdh/laravel-snappy와 연동해 Blade 템플릿에서 손쉽게 PDF를 생성하도록 고려합니다.

마무리 생각

올바른 단계와 적절한 의존성을 설치하면 Ubuntu에서 WKHTMLtoPDF를 손쉽게 설치할 수 있습니다. 자동 보고서, 청구서, 동적 PDF 시스템을 구축하든, WKHTMLtoPDF는 서버‑사이드 HTML‑to‑PDF 변환을 위한 신뢰할 수 있는 솔루션입니다.