차동훈
(출처 : https://wkhtmltopdf.org/index.html)
웹 페이지나 HTML 문서를 PDF로 변환해야 할 때가 종종 있습니다.
보고서를 만들거나, 웹사이트의 특정 내용을 오프라인으로 보존하고 싶을 때 유용한 기능이죠.
오늘은 이럴 때 매우 강력하고 유용하게 사용할 수 있는 도구인 wkhtmltopdf를 Ubuntu 24.04 시스템에 설치하고 사용하는 방법을 자세히 알아보겠습니다.
wkhtmltopdf는 HTML 문서를 PDF로 변환하는 데 최적화된 오픈소스 유틸리티로, 렌더링 엔진으로 WebKit을 사용하기 때문에 웹 브라우저에서 보이는 것과 거의 동일한 결과물을 PDF로 얻을 수 있다는 장점이 있습니다.
1. wkhtmltopdf 다운로드 및 설치 (Ubuntu 24.04)
wkhtmltopdf는 공식 다운로드 페이지(https://wkhtmltopdf.org/downloads.html)에서 다양한 시스템 및 버전별 패키지를 제공합니다.
하지만 아쉽게도 현재(2025년 6월 12일 기준) Ubuntu 24.04에 직접적으로 호환되는 최신 버전 패키지는 제공되지 않고 있습니다.
이럴 때는 Ubuntu 22.04(코드명 Jammy)용 패키지를 다운로드하여 설치할 수 있습니다.
Ubuntu는 하위 버전 호환성이 뛰어난 편이므로, 이 방법으로도 대부분 문제없이 사용할 수 있습니다.
먼저, 터미널을 열고 다음 명령어를 사용하여 wkhtmltopdf 패키지를 다운로드합니다.
이 예시에서는 0.12.6.1-2 버전을 사용합니다.
# wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb
다운로드가 완료되면 dpkg 명령어를 사용하여 패키지를 설치합니다.
설치 도중 다음과 같은 오류 메시지가 나타날 수 있습니다.
# dpkg -i wkhtmltox_0.12.6.1-2.jammy_amd64.deb
dpkg: dependency problems prevent configuration of wkhtmltox:
wkhtmltox depends on xfonts-75dpi; however:
Package xfonts-75dpi is not installed.
wkhtmltox depends on xfonts-base; however:
Package xfonts-base is not installed.
이는 필요한 의존성 패키지가 없기 때문입니다. 이럴 때는 아래 명령어를 사용하여 누락된 패키지들을 설치하고, 깨진 의존성을 해결해줍니다.
# apt install -y xfonts-75dpi xfonts-base
# apt –fix-broken install
명령어는 시스템에 설치되지 않아 발생한 의존성 문제를 자동으로 해결해주는 매우 유용한 명령어입니다.
이 명령어를 실행하면 wkhtmltopdf 설치도 정상적으로 마무리될 것입니다.
2. 한글 사용을 위한 폰트 설치
wkhtmltopdf를 사용하여 한글이 포함된 HTML 문서를 PDF로 변환할 경우, 폰트가 깨지거나 제대로 표시되지 않을 수 있습니다.
이를 방지하기 위해 한글 폰트를 설치해 주는 것이 좋습니다. 나눔 폰트, Noto CJK 폰트, 그리고 Unfonts-core 폰트가 일반적으로 많이 사용됩니다.
다음 명령어를 사용하여 필요한 한글 폰트 패키지를 설치합니다.
# apt -y install fonts-nanum
# apt -y install fonts-noto-cjk fonts-unfonts-core
이제 wkhtmltopdf가 한글 텍스트도 완벽하게 처리할 수 있게 되었습니다.
3. wkhtmltopdf 사용 방법
wkhtmltopdf는 로컬의 HTML 파일뿐만 아니라, 특정 웹사이트 URL을 직접 PDF로 변환할 수 있는 강력한 기능을 제공합니다. 기본적인 사용법은 매우 직관적입니다.
3.1. 로컬 HTML 파일을 PDF로 변환하기
로컬에 저장된 HTML 파일을 PDF로 변환하려면 다음과 같이 사용합니다.
# wkhtmltopdf –encoding UTF-8 –enable-local-file-access report.html report.pdf
–encoding UTF-8: HTML 파일의 인코딩이 UTF-8인 경우 지정해줍니다. 한글 깨짐 방지에 중요합니다.
–enable-local-file-access: HTML 파일 내에 이미지나 CSS 파일 등 로컬 경로의 리소스가 포함되어 있다면 이 옵션을 사용해야 정상적으로 불러올 수 있습니다.
report.html: PDF로 변환할 원본 HTML 파일명입니다.
report.pdf: 생성될 PDF 파일명입니다.
3.2. 웹사이트 URL을 PDF로 변환하기
특정 웹 페이지를 PDF로 저장하고 싶다면 URL을 직접 입력할 수 있습니다.
# wkhtmltopdf http://www.sysdocu.kr/text.html text.pdf
http://www.sysdocu.kr/text.html: PDF로 변환할 웹 페이지의 URL입니다.
text.pdf: 생성될 PDF 파일명입니다.
마치며
이렇게 wkhtmltopdf를 Ubuntu 24.04 시스템에 설치하고 사용하는 방법을 자세히 알아보았습니다.
간단한 명령어로도 복잡한 HTML 문서를 고품질의 PDF 파일로 손쉽게 변환할 수 있다는 것을 확인하셨을 겁니다.
보고서 생성, 웹 콘텐츠 보존 등 다양한 상황에서 wkhtmltopdf가 여러분의 작업을 훨씬 더 효율적으로 만들어 줄 것입니다.
다음에도 유용한 정보를 들고 찾아오겠습니다. 감사합니다.