How To Install Wkhtmltopdf on Ubuntu 24.04 LTS

Converting web pages to PDF format is a common requirement for many web developers, system administrators, and regular users. Whether you need to generate reports, create documentation, or simply archive web content, having a reliable HTML-to-PDF conversion tool is essential. Wkhtmltopdf stands out as a powerful command-line utility that excels at this task, and in this comprehensive guide, we’ll walk through the process of installing it on Ubuntu 24.04 LTS (Noble Numbat).

Understanding Wkhtmltopdf

Wkhtmltopdf is an open-source command-line tool that renders HTML content into PDF documents using the Qt WebKit rendering engine. This powerful utility can handle complex layouts, CSS styling, and JavaScript, making it ideal for generating high-quality PDF documents from web pages.

What makes wkhtmltopdf special?

The tool runs entirely “headless,” meaning it doesn’t require a display or display service to operate. This makes it particularly suitable for server environments where graphical interfaces aren’t available. Along with wkhtmltopdf, the package also typically includes wkhtmltoimage, which performs similar conversions but outputs to various image formats instead of PDF.

Development status consideration

It’s important to note that wkhtmltopdf has been abandoned and is no longer being actively updated. While it remains functional and is still widely used, this abandonment status may impact long-term viability. For new projects, you might want to consider alternatives, which we’ll discuss later in this article.

Common use cases

Wkhtmltopdf proves invaluable for numerous applications:

• Generating invoices and receipts for e-commerce websites
• Creating printable reports from web applications
• Archiving web content in a format that preserves layout and styling
• Producing documents from template-based systems
• Integrating with larger applications like Odoo ERP for report generation

Prerequisites for Installation

Before installing wkhtmltopdf on your Ubuntu 24.04 system, ensure you have the following prerequisites in place.

System requirements:

• A running Ubuntu 24.04 LTS (Noble Numbat) system
• Administrative (sudo) privileges
• Internet connection for downloading packages
• Terminal access to your system

Package requirements:

• Basic utilities including wget for downloading files
• Font packages that wkhtmltopdf depends on

Let’s begin by updating your system’s package index:

sudo apt update

Installation Methods

There are several ways to install wkhtmltopdf on Ubuntu 24.04. We’ll cover three primary methods, each with its own advantages and considerations.

Method 1: Using the Ubuntu Repository

The simplest approach is to install wkhtmltopdf directly from the Ubuntu repositories. While this method is straightforward, it may not provide the latest version with all features.

sudo apt install wkhtmltopdf

This will install version 0.12.6-2build2, which is available in the Ubuntu 24.04 (Noble) universe repository. However, this version may be built against an unpatched version of Qt, which means some advanced features might not be available.

Method 2: Using Prebuilt Packages (Recommended)

For a more feature-complete installation with patched Qt support, installing from prebuilt packages is recommended. This method ensures you get a version with all capabilities enabled.

First, install the required dependencies:

sudo apt update
sudo apt install -y wget xfonts-75dpi

Next, download the appropriate wkhtmltopdf package. Currently, there isn’t a specific build for Ubuntu 24.04, but the Ubuntu 22.04 (Jammy) package works perfectly:

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

Install the downloaded package:

sudo dpkg -i wkhtmltox_0.12.6.1-2.jammy_amd64.deb

This may result in dependency errors, which can be resolved by running:

sudo apt install -f

The above command will automatically install any missing dependencies and complete the wkhtmltopdf installation.

Method 3: Manual Installation

For users who require specific versions or configurations, manual installation provides the most control.

First, download your preferred version from the wkhtmltopdf GitHub releases page. Then proceed with installation as outlined in Method 2.

Handling Dependencies

Wkhtmltopdf depends on several system libraries and components to function correctly. Let’s address these dependencies to ensure a smooth installation.

Required system libraries:

The most common dependencies include:

• X11 libraries for rendering
• Font configurations and packages
• Qt libraries that power the WebKit engine

If you used Method 2 or 3 and encountered dependency issues, resolve them with:

sudo apt install -f

This command will analyze the installed package and automatically install any missing dependencies.

Font-related dependencies:

For proper rendering of documents, make sure font packages are installed:

sudo apt install xfonts-75dpi xfonts-base

These packages ensure that wkhtmltopdf has access to the fonts needed for rendering documents correctly.

Post-Installation Configuration

After installation, a few configuration steps will ensure wkhtmltopdf works optimally on your system.

Verifying the Installation

First, let’s verify that wkhtmltopdf was installed correctly:

wkhtmltopdf --version

You should see output similar to:

wkhtmltopdf 0.12.6 (with patched qt)

The “(with patched qt)” part indicates that you have the fully-featured version with patched Qt support.

Setting Up Symbolic Links

If you installed using Method 2 or 3, the executable files are typically installed in /usr/local/bin/. To ensure system-wide access, symbolic links might be necessary if they weren’t automatically created:

sudo ln -s /usr/local/bin/wkhtmltopdf /usr/bin/wkhtmltopdf
sudo ln -s /usr/local/bin/wkhtmltoimage /usr/bin/wkhtmltoimage

Permission Settings

Ensure that the wkhtmltopdf binary has the correct execution permissions:

sudo chmod +x /usr/local/bin/wkhtmltopdf
sudo chmod +x /usr/local/bin/wkhtmltoimage

Testing Your Installation

Let’s perform a basic test to confirm that wkhtmltopdf is working correctly.

Basic Functionality Test

Create a simple PDF from a website:

wkhtmltopdf https://ubuntu.com/ ubuntu.pdf

This command fetches the Ubuntu website and converts it to a PDF named ubuntu.pdf in your current directory.

Common Testing Issues

If you encounter errors during testing, they typically fall into one of these categories:

X11 server errors:

If you see errors related to X11 or display, it may indicate that the headless rendering isn’t working correctly. For server environments without a display, you might need to use xvfb:

sudo apt install xvfb
xvfb-run wkhtmltopdf https://ubuntu.com/ ubuntu.pdf

Font rendering problems:

If the generated PDF shows font issues, ensure you’ve installed the font packages mentioned earlier. Additional font packages may be needed depending on the content you’re converting.

Memory-related errors:

For large or complex pages, wkhtmltopdf might run out of memory. Consider using the --lowquality option or increasing available system memory.

Advanced Usage

Wkhtmltopdf offers numerous command-line options for customizing the output.

Command-Line Options

Here are some useful options to customize your PDF outputs:

Page size and orientation:

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

Margins:

wkhtmltopdf --margin-top 20 --margin-bottom 20 --margin-left 20 --margin-right 20 https://ubuntu.com/ ubuntu-margins.pdf

Headers and footers:

wkhtmltopdf --header-html header.html --footer-html footer.html https://ubuntu.com/ ubuntu-with-header-footer.pdf

Quality settings:

wkhtmltopdf --dpi 300 https://ubuntu.com/ ubuntu-high-dpi.pdf

Integration with Web Applications

Wkhtmltopdf can be called from various programming languages and frameworks:

Python integration:

import subprocess
subprocess.run(["wkhtmltopdf", "https://ubuntu.com/", "ubuntu.pdf"])

PHP integration:

<?php
exec("wkhtmltopdf https://ubuntu.com/ ubuntu.pdf");
?>

Node.js integration:

const { exec } = require('child_process');
exec('wkhtmltopdf https://ubuntu.com/ ubuntu.pdf', (error, stdout, stderr) => {
  if (error) {
    console.error(`Error: ${error.message}`);
    return;
  }
  console.log('PDF created successfully');
});

Using Wkhtmltopdf with Odoo

Odoo, a popular open-source ERP system, relies on wkhtmltopdf for report generation. Setting up wkhtmltopdf correctly is crucial for Odoo’s reporting functionality.

Odoo Requirements

Odoo 18 (and other recent versions) requires wkhtmltopdf version 0.12.5 or higher with patched Qt support. Using the wrong version can lead to formatting issues in reports.

Installation for Odoo

For Odoo 18 on Ubuntu 24.04, you can install wkhtmltopdf as follows:

sudo wget https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.5/wkhtmltox_0.12.5-1.bionic_amd64.deb
sudo dpkg -i wkhtmltox_0.12.5-1.bionic_amd64.deb
sudo apt install -f

After installation, verify that Odoo can access wkhtmltopdf by checking the Odoo system information page in the administration section.

Known Issues and Limitations

Being aware of wkhtmltopdf’s limitations will help you make informed decisions about its use.

Ubuntu 24.04 Specific Challenges

Since Ubuntu 24.04 is relatively new, there might not be official wkhtmltopdf packages specifically built for it. Using packages from Ubuntu 22.04 (Jammy) generally works well but may occasionally present compatibility issues.

Performance Considerations

Wkhtmltopdf can be memory-intensive when rendering complex web pages. For server environments with limited resources, consider:

• Using the --lowquality option for less resource-intensive rendering
• Simplifying input HTML for faster processing
• Implementing queuing systems for high-volume PDF generation

Feature Limitations

The abandoned status of wkhtmltopdf means that some modern web features might not render correctly, and bugs won’t be fixed. Common limitations include:

• Inconsistent rendering of advanced CSS features
• Variable handling of JavaScript-heavy pages
• Limited support for HTML5 features

Alternative Solutions

Given wkhtmltopdf’s abandoned status, it’s worth considering alternatives for new projects.

Chrome/Chromium Headless Mode

Google Chrome’s headless mode offers an excellent alternative with better support for modern web standards:

sudo apt install google-chrome-stable
google-chrome --headless --disable-gpu --run-all-compositor-stages-before-draw --print-to-pdf=output.pdf https://ubuntu.com/

This approach leverages Chrome’s modern rendering engine for potentially better results with complex web pages.

Other HTML-to-PDF Tools

Several other tools can convert HTML to PDF:

• Puppeteer: A Node.js library that provides a high-level API to control Chrome
• WeasyPrint: A Python library for document generation
• PrinceXML: A commercial solution with excellent CSS support

Each alternative has its own strengths and weaknesses regarding rendering quality, performance, and ease of integration.

Troubleshooting Guide

Even with careful installation, you might encounter issues with wkhtmltopdf. Here are solutions to common problems.

Common Error Messages

“Error: This version of wkhtmltopdf is built against an unpatched version of QT”

This indicates you’re using the repository version without patched Qt. Install the prebuilt package as described in Method 2.

“Cannot connect to X server”

Wkhtmltopdf needs an X server environment. On headless servers, install and use xvfb:

sudo apt install xvfb
xvfb-run wkhtmltopdf input.html output.pdf

“The switch –disable-smart-shrinking is not supported using unpatched qt”

This confirms you’re using an unpatched Qt version. Install the version with patched Qt as described earlier.

Dependency-Related Issues

If dpkg reports missing dependencies during installation, resolve them with:

sudo apt --fix-broken install

or

sudo apt install -f

Version Conflicts

If you have multiple versions installed or paths configured incorrectly, check where wkhtmltopdf is being called from:

which wkhtmltopdf

To force using a specific version, use the full path to the binary:

/usr/local/bin/wkhtmltopdf input.html output.pdf

Congratulations! You have successfully installed Wkhtmltopdf. Thanks for using this tutorial for installing the Wkhtmltopdf on Ubuntu 24.04 LTS system. For additional help or useful information, we recommend you check the official Wkhtmltopdf website.