Install wkhtmltopdf on Ubuntu 24.04 and verify it works

On Ubuntu 24.04 (Noble), the simplest installation is the Ubuntu archive package: sudo apt update && sudo apt install wkhtmltopdf. Ubuntu lists the amd64 package as 0.12.6-2build2 in Universe. Then check which executable your shell finds with command -v wkhtmltopdf, inspect its build with wkhtmltopdf --version, and render a small local HTML file to confirm conversion works.

The Ubuntu package uses Qt 5 and Qt WebKit dependencies, and its package listing recommends an X server or Xvfb. Upstream distinguishes builds made with patched Qt; do not assume every package has the same behavior or features. If your application specifically requires a patched-Qt build, verify the actual build and the behavior you need before deploying it. Ubuntu package details · upstream packaging notes.

1. Install the Ubuntu 24.04 archive package

Refresh APT metadata and install the package from the Ubuntu repositories:

sudo apt update
sudo apt install wkhtmltopdf

The Noble archive package is in the Universe component. Package availability depends on your configured Ubuntu repositories. This route uses Ubuntu’s packaged build and package management to handle its declared dependencies.

Confirm the installed package version and executable path:

command -v wkhtmltopdf
wkhtmltopdf --version
apt-cache policy wkhtmltopdf

The archive package version identified for Noble amd64 is 0.12.6-2build2. The executable will commonly resolve under /usr/bin, but check your machine instead of treating a particular path as proof of success.

2. Consider the upstream patched-Qt package only if you need it

Some wkhtmltopdf workflows depend on behavior associated with the upstream patched-Qt build. Upstream’s packaging project describes patched Qt as a meaningful build distinction, and its download guidance says some features require it. Check the specific feature your application uses and verify the build’s output; the two package routes are not interchangeable by version number alone.

A third-party guide reports that the upstream 0.12.6.1-3 Jammy amd64 package can work on Noble after installing its font and runtime dependencies, including xfonts-75dpi and xfonts-base. That is a reported installation recipe, not an Ubuntu endorsement or a compatibility guarantee. It is also a different build from Noble’s 0.12.6-2build2 archive package. See the upstream downloads page and the packaging repository before selecting a build.

If you choose that route, download only the package matching the machine architecture and follow the package’s documented dependencies. A typical install sequence for a downloaded local .deb is:

# Install the downloaded file, allowing APT to resolve dependencies.
sudo apt install ./wkhtmltox_0.12.6.1-3.jammy_amd64.deb

# If APT reports an interrupted or incomplete dependency configuration:
sudo apt --fix-broken install

Do not use that Jammy filename on a different architecture. After installation, check for multiple copies: the reported upstream package may install to /usr/local/bin/wkhtmltopdf, while the archive package may resolve to /usr/bin/wkhtmltopdf.

3. Verify wkhtmltopdf works with a real conversion

First identify the executable and its build:

command -v wkhtmltopdf
wkhtmltopdf --version

Then create a tiny local HTML document, render it, and inspect the result:

cat > /tmp/wkhtmltopdf-check.html <<'HTML'
<!doctype html>
<html>
  <head><meta charset="utf-8"><title>Smoke test</title></head>
  <body><h1>wkhtmltopdf check</h1><p>Local render succeeded.</p></body>
</html>
HTML

wkhtmltopdf /tmp/wkhtmltopdf-check.html /tmp/wkhtmltopdf-check.pdf
file /tmp/wkhtmltopdf-check.pdf

A successful smoke test should exit without a conversion error and create a PDF that file identifies as a PDF document. Open it with a PDF viewer if you also need to check that the rendered page looks right. This local-file test avoids network and remote-site variables; it does not prove every website, font, JavaScript workflow, or application-specific option will render correctly.

4. Common options and practical usage

For ordinary conversions, the command takes an input URL or HTML file followed by an output path:

wkhtmltopdf [options] input.html output.pdf
wkhtmltopdf [options] https://example.com output.pdf

For a server-side job, make output paths explicit and keep inputs accessible to the process running the command. If converting remote pages, network access, redirects, authentication, page load timing, and referenced assets can affect the result. Start with a simple page, then add your real input and options one at a time.

See the installed command’s help for the options supported by that exact build:

wkhtmltopdf --help

Build differences matter: options or behavior that rely on patched Qt may not work the same way in Ubuntu’s archive build. Test the options required by your application against the binary you will deploy.

5. Headless servers, dependencies, and deployment

Ubuntu’s package listing includes Qt 5 and Qt WebKit dependencies and recommends an X server or Xvfb. Runtime needs can vary with the environment and selected build, especially on a headless server. If the command installs but fails during rendering on a server, check the error output, available runtime libraries, fonts, and whether the environment needs an X server or Xvfb.

For repeatable deployments:

Install from a defined package source and record the package version.
Check command -v wkhtmltopdf in the same user or service environment that performs conversion.
Run the smoke test as that service user, with its real permissions and environment.
Include fonts and any required runtime support in the deployment image or host setup.
Keep a representative HTML-to-PDF conversion in your release checks if PDF output is a core application function.

6. Troubleshooting

Symptom	Likely cause	What to do
`E: Unable to locate package wkhtmltopdf`	APT metadata is stale or the Universe component is not enabled in the configured repositories.	Run `sudo apt update`, check your Ubuntu repository configuration for Universe, then retry. Ubuntu lists the Noble package in Universe.
`command -v wkhtmltopdf` returns nothing	The package did not install, or its executable directory is not on this shell’s `PATH`.	Check `dpkg -l wkhtmltopdf`, review the install output, and inspect `PATH`. Reinstall through the package source you selected if necessary.
The path points to an unexpected binary	More than one installation may exist, such as copies in `/usr/bin` and `/usr/local/bin`.	Run `type -a wkhtmltopdf` and `wkhtmltopdf --version`. Remove ambiguity by fixing the service’s `PATH` or removing the unintended installation through its package manager.
A downloaded `.deb` reports unmet dependencies	The selected package needs runtime or font packages absent from the system, or it does not match the distribution or architecture.	Read the package manager’s dependency list and use APT to install or repair dependencies. The cited third-party Jammy-on-Noble guide reports missing font packages as a common issue for that route; it does not guarantee compatibility.
Conversion fails only on a headless host	The runtime environment may lack display support or libraries expected by the selected build.	Review the package’s X server/Xvfb recommendation and the build’s runtime requirements. Re-run the local smoke test under the same service account and environment.
The PDF is created but lacks expected headers, footers, or other behavior	The installed build may not include patched Qt, or the input/options may not be supported as expected.	Check the version output and confirm whether the required feature depends on patched Qt. Test the exact feature on the selected build before changing the production workflow.
Local HTML works, remote URL fails or looks incomplete	The process may not reach the site or its assets, or the page may need more time or browser behavior than this build provides.	Check network access and the command’s diagnostics; compare with a minimal local file. Verify the output for the exact remote page rather than assuming a local smoke test covers it.

7. Performance, reliability, and cost notes

Installation itself does not establish rendering speed or reliability for your workload. Conversion time depends on the page, its assets, runtime environment, and options. Keep pages and dependencies available to the process, avoid unnecessary remote resources, and measure representative documents on the target host if throughput matters.

For a server workflow, handle a nonzero command exit status as a failed conversion, check that the output exists and is nonempty, and retain diagnostic output for failures. If you need a particular rendering feature, verify it against the installed build. Package version and --version output help make environment differences diagnosable.

The Ubuntu archive route uses Ubuntu’s package manager; a downloaded upstream package is a separate installation choice with its own dependency and maintenance considerations. No performance benchmark or compatibility guarantee is implied here.

Or skip the browser setup

If your goal is to capture a public webpage as an image or PDF rather than install a local HTML-to-PDF binary, ScreenshotNeo is a website screenshot API and MCP server. A single request can return a screenshot or PDF. The API supports options such as full-page capture, element selection, device presets, custom CSS and JavaScript, and PDF page settings. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie and consent banners like a visitor, then removes 60+ known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, with the response indicating the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients. The Free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots, and every feature is on every plan.

FAQ

Does installing wkhtmltopdf prove my application can generate its PDFs?

No. The smoke test verifies a basic local conversion. Run a representative document through the same binary and runtime environment your application uses.

Should I use the Ubuntu package or the upstream package?

Use Ubuntu’s archive package for the straightforward Noble APT installation. Consider another build only when you have a specific requirement, and verify both its version and required behavior. The reported Jammy package compatibility is third-party guidance, not a guarantee.

Can ScreenshotNeo replace wkhtmltopdf for local HTML files?

ScreenshotNeo is for capturing webpages through its API or MCP server. The wkhtmltopdf steps above cover converting a local HTML file with a local command-line tool.