wkhtmltopdf is a command-line tool that converts HTML pages to PDF documents and images using the Qt WebKit rendering engine. It runs headless – no display server required – making it a solid choice for generating PDFs on servers, in CI/CD pipelines, and inside web applications. The companion tool wkhtmltoimage handles HTML-to-image conversion in formats like PNG and JPG.

This guide walks through installing wkhtmltopdf and wkhtmltoimage on RHEL 10 / Rocky Linux 10 / AlmaLinux 10 and Ubuntu 24.04, verifying the installation, and putting the tools to practical use.

Prerequisites

Before you begin, confirm the following:

  • A running instance of RHEL 10, Rocky Linux 10, AlmaLinux 10, or Ubuntu 24.04
  • A user account with sudo privileges
  • Internet access to pull packages from GitHub releases
  • Basic familiarity with the Linux terminal

Step 1 – Install Required Dependencies

wkhtmltopdf relies on several shared libraries for rendering fonts and graphics. Install them first so the main package pulls in cleanly.

On RHEL 10 / Rocky Linux 10 / AlmaLinux 10

sudo dnf install -y libXrender libXext fontconfig freetype libpng libjpeg-turbo xorg-x11-fonts-Type1 xorg-x11-fonts-75dpi

Verify the libraries are in place:

rpm -q libXrender libXext fontconfig freetype

On Ubuntu 24.04

sudo apt update
sudo apt install -y libxrender1 libxext6 fontconfig libfreetype6 libjpeg-turbo8 libpng16-16t64 xfonts-75dpi xfonts-base

Confirm the packages installed correctly:

dpkg -l | grep -E "libxrender1|libxext6|fontconfig"

Step 2 – Download wkhtmltopdf from GitHub Releases

The upstream project distributes pre-built packages through GitHub. At the time of writing, the latest stable release is 0.12.6.1-3. Check the releases page for the newest version before proceeding.

On RHEL 10 / Rocky Linux 10 / AlmaLinux 10

Download the RPM package:

cd /tmp
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox-0.12.6.1-3.almalinux9.x86_64.rpm

Install the downloaded RPM using dnf:

sudo dnf localinstall -y /tmp/wkhtmltox-0.12.6.1-3.almalinux9.x86_64.rpm

The dnf localinstall command handles dependency resolution automatically, pulling in anything the RPM needs from your configured repositories.

On Ubuntu 24.04

Download the Debian package:

cd /tmp
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.jammy_amd64.deb

Install using dpkg, then fix any missing dependencies:

sudo dpkg -i /tmp/wkhtmltox_0.12.6.1-3.jammy_amd64.deb
sudo apt install -f -y

Running apt install -f after dpkg resolves any dependency gaps that dpkg itself cannot handle.

Step 3 – Verify the Installation

Confirm that both wkhtmltopdf and wkhtmltoimage are installed and accessible:

wkhtmltopdf --version

Expected output:

wkhtmltopdf 0.12.6.1 (with patched qt)
wkhtmltoimage --version

Check the binary location:

which wkhtmltopdf wkhtmltoimage

Both binaries should reside under /usr/local/bin/.

Step 4 – Basic Usage – Convert URL to PDF

The simplest use case is converting a live web page to a PDF file:

wkhtmltopdf https://example.com example.pdf

Verify the output file was created:

ls -lh example.pdf
file example.pdf

The file command should report the output as a PDF document.

Step 5 – Convert a Local HTML File to PDF

Create a sample HTML file for testing:

cat << 'EOF' > /tmp/sample.html
<!DOCTYPE html>
<html>
<head><title>Test PDF</title></head>
<body>
  <h1>PDF Generation Test</h1>
  <p>This document was generated by wkhtmltopdf on a Linux server.</p>
</body>
</html>
EOF

Convert it:

wkhtmltopdf /tmp/sample.html /tmp/sample.pdf

Check the result:

ls -lh /tmp/sample.pdf

Step 6 – Custom Page Size, Orientation, and Margins

wkhtmltopdf supports a wide range of layout options. Here are the most commonly used flags.

Set page size and orientation

wkhtmltopdf --page-size A4 --orientation Landscape https://example.com landscape.pdf

Set custom margins

wkhtmltopdf --margin-top 20mm --margin-bottom 20mm --margin-left 15mm --margin-right 15mm https://example.com margins.pdf

Use Letter size with narrow margins

wkhtmltopdf --page-size Letter --margin-top 10mm --margin-bottom 10mm --margin-left 10mm --margin-right 10mm https://example.com letter.pdf

Verify each output file exists and is a valid PDF:

file landscape.pdf margins.pdf letter.pdf

Step 7 – Add Headers and Footers

You can inject headers and footers into every page of the generated PDF. These can be plain text or HTML templates.

Simple text header and footer

wkhtmltopdf \
  --header-center "Company Report" \
  --header-font-size 10 \
  --header-spacing 5 \
  --footer-center "Page [page] of [topage]" \
  --footer-font-size 9 \
  --footer-spacing 5 \
  https://example.com report.pdf

HTML header template

For richer formatting, create an HTML file for the header:

cat << 'EOF' > /tmp/header.html
<!DOCTYPE html>
<html>
<head>
  <style>
    body { font-family: Arial, sans-serif; font-size: 10px; margin: 0; padding: 5px 20px; }
    .header-bar { border-bottom: 1px solid #333; padding-bottom: 5px; display: flex; justify-content: space-between; }
  </style>
</head>
<body>
  <div class="header-bar">
    <span>Internal Document</span>
    <span>Generated: 2026-03-18</span>
  </div>
</body>
</html>
EOF

Use it with the --header-html flag:

wkhtmltopdf --header-html /tmp/header.html --margin-top 25mm https://example.com with-header.pdf

Bump the top margin when using HTML headers so the content does not overlap the header area.

Step 8 – Convert HTML to Images with wkhtmltoimage

wkhtmltoimage works the same way but produces image files instead of PDFs.

Convert a URL to PNG

wkhtmltoimage https://example.com example.png

Convert to JPG with custom quality and width

wkhtmltoimage --format jpg --quality 85 --width 1280 https://example.com example.jpg

Capture a local HTML file

wkhtmltoimage /tmp/sample.html /tmp/sample.png

Verify the generated images:

file example.png example.jpg /tmp/sample.png

Step 9 – Use wkhtmltopdf in Shell Scripts

wkhtmltopdf fits naturally into automated workflows. Here is a straightforward script that generates a dated report:

#!/bin/bash
# generate-report.sh - Create a PDF report from a URL

URL="$1"
DATE=$(date +%Y-%m-%d)
OUTPUT="/var/reports/report-${DATE}.pdf"

if [ -z "$URL" ]; then
  echo "Usage: $0 <url>"
  exit 1
fi

mkdir -p /var/reports

wkhtmltopdf \
  --page-size A4 \
  --margin-top 20mm \
  --margin-bottom 20mm \
  --footer-center "Generated on ${DATE} - Page [page] of [topage]" \
  --footer-font-size 8 \
  --quiet \
  "$URL" "$OUTPUT"

if [ $? -eq 0 ]; then
  echo "Report saved to ${OUTPUT}"
  echo "File size: $(du -h "$OUTPUT" | cut -f1)"
else
  echo "PDF generation failed" >&2
  exit 1
fi

Make it executable and run it:

chmod +x generate-report.sh
./generate-report.sh https://example.com

Step 10 – Use in Web Applications

Most programming languages can call wkhtmltopdf through a subprocess or a wrapper library. Below are quick examples.

Python

import subprocess

def html_to_pdf(input_path, output_path):
    result = subprocess.run(
        ['wkhtmltopdf', '--quiet', input_path, output_path],
        capture_output=True, text=True
    )
    if result.returncode != 0:
        raise RuntimeError(f"wkhtmltopdf failed: {result.stderr}")
    return output_path

html_to_pdf('/tmp/sample.html', '/tmp/output.pdf')

The pdfkit Python library wraps wkhtmltopdf with a cleaner API if you prefer:

pip install pdfkit
import pdfkit
pdfkit.from_url('https://example.com', 'output.pdf')
pdfkit.from_file('/tmp/sample.html', 'sample.pdf')
pdfkit.from_string('<h1>Hello</h1>', 'hello.pdf')

PHP

$output = shell_exec('wkhtmltopdf --quiet https://example.com /tmp/output.pdf 2>&1');
if (file_exists('/tmp/output.pdf')) {
    echo "PDF generated successfully";
}

Comparison with Alternatives

wkhtmltopdf is not the only HTML-to-PDF tool available. Here is how it stacks up against two popular alternatives.

Feature wkhtmltopdf Puppeteer (Headless Chrome) WeasyPrint
Rendering Engine Qt WebKit Chromium/Blink Custom (CSS-focused)
JavaScript Support Partial Full None
CSS Support Good (older standards) Excellent (modern CSS) Good (print-focused CSS)
Memory Usage Low High (full browser) Moderate
Installation Size Small Large (bundles Chromium) Small
CLI Tool Yes (native) Requires Node.js script Yes (native)
Active Development Maintenance mode Active Active
Best For Simple, fast PDF generation Complex JS-heavy pages CSS print stylesheets

When to choose wkhtmltopdf: You need a lightweight, standalone binary that handles straightforward HTML-to-PDF conversion without pulling in a full browser runtime. It works well for invoices, reports, and documentation where modern JavaScript rendering is not a requirement.

When to consider Puppeteer: Your pages rely heavily on JavaScript frameworks (React, Vue, Angular) or require modern CSS features like Grid and Flexbox.

When to consider WeasyPrint: You are building PDF output from CSS print stylesheets and do not need JavaScript support at all. Written in Python, it integrates smoothly with Django and Flask applications.

Troubleshooting

Error: cannot connect to X server

wkhtmltopdf requires a display server on some older builds. If you hit this error, use xvfb-run to provide a virtual framebuffer:

# RHEL 10 / Rocky Linux 10 / AlmaLinux 10
sudo dnf install -y xorg-x11-server-Xvfb

# Ubuntu 24.04
sudo apt install -y xvfb

Then prefix your command:

xvfb-run wkhtmltopdf https://example.com output.pdf

The patched Qt builds (indicated by “with patched qt” in the version output) should not need this workaround.

Missing fonts or broken characters

If the generated PDF shows squares or question marks instead of text, install additional font packages:

# RHEL 10 / Rocky Linux 10 / AlmaLinux 10
sudo dnf install -y google-noto-sans-fonts google-noto-serif-fonts

# Ubuntu 24.04
sudo apt install -y fonts-noto fonts-liberation

Rebuild the font cache afterward:

sudo fc-cache -fv

SSL certificate errors

When converting HTTPS URLs and you encounter certificate verification failures:

wkhtmltopdf --no-stop-slow-scripts --ssl-crt-path /etc/ssl/certs https://example.com output.pdf

For testing environments only, you can bypass SSL checks entirely:

wkhtmltopdf --disable-smart-shrinking --no-stop-slow-scripts https://self-signed.example.com output.pdf

Do not disable SSL verification in production.

Blank or incomplete PDF output

Pages that load content via JavaScript may render blank because wkhtmltopdf finishes before the scripts complete. Add a delay:

wkhtmltopdf --javascript-delay 3000 --no-stop-slow-scripts https://example.com output.pdf

The --javascript-delay value is in milliseconds. Increase it if your page needs more time to load.

Permission denied on output file

Make sure the target directory exists and your user has write permissions:

mkdir -p /var/reports
sudo chown $USER:$USER /var/reports

Check shared library dependencies

If wkhtmltopdf crashes or throws library errors, inspect what it needs:

ldd $(which wkhtmltopdf) | grep "not found"

Install any missing libraries reported by ldd, then test again.

Conclusion

You now have wkhtmltopdf and wkhtmltoimage installed and working on your RHEL 10, Rocky Linux 10, AlmaLinux 10, or Ubuntu 24.04 system. The tools handle straightforward HTML-to-PDF and HTML-to-image conversion with minimal resource overhead. For pages that rely on modern JavaScript frameworks, consider Puppeteer or a similar Chromium-based solution. For CSS print stylesheet workflows, WeasyPrint is worth evaluating. For everything else – invoices, reports, documentation, server-side batch processing – wkhtmltopdf remains a reliable, battle-tested option.

RELATED ARTICLESMORE FROM AUTHOR

LEAVE A REPLY

Please enter your comment!
Please enter your name here