Install wkhtmltopdf on Ubuntu 24.04

Use Ubuntu’s repository package on Ubuntu 24.04 (Noble):

sudo apt update
sudo apt install wkhtmltopdf
wkhtmltopdf --version
command -v wkhtmltopdf

Noble provides wkhtmltopdf version 0.12.6-2build2 in the Universe repository for amd64. APT is the recommended first route because it resolves the package’s Qt, WebKit, printing, SVG, widgets, and C++ runtime dependencies. The Ubuntu build uses unpatched Qt, so some options associated with upstream’s patched-Qt builds may be unavailable.

1. Install the Ubuntu 24.04 package

Check that Universe is enabled

Ubuntu 24.04 normally has Universe enabled. If APT cannot find the package, enable it and refresh the package index:

sudo add-apt-repository universe
sudo apt update

Then install the package:

sudo apt install wkhtmltopdf

Confirm the executable and version:

command -v wkhtmltopdf
wkhtmltopdf --version

You should see a path such as /usr/bin/wkhtmltopdf and an Ubuntu-packaged 0.12.6 version. The exact revision is shown by APT:

apt-cache policy wkhtmltopdf

Ubuntu’s Noble package listing is available at packages.ubuntu.com/noble/wkhtmltopdf. The package is installed through APT rather than directly with dpkg; dpkg does not automatically download missing dependencies.

2. Run a controlled smoke test

Use a page you control or a simple public test page to verify that conversion works:

mkdir -p "$HOME/wkhtmltopdf-test"
wkhtmltopdf https://example.com "$HOME/wkhtmltopdf-test/example.pdf"
file "$HOME/wkhtmltopdf-test/example.pdf"
ls -lh "$HOME/wkhtmltopdf-test/example.pdf"

This checks invocation and output creation. It does not prove that every JavaScript-heavy site, font, header, footer, or CSS feature will render correctly.

The basic command pattern is:

wkhtmltopdf [global options] <input URL or HTML file> <output PDF>

For a local HTML file:

wkhtmltopdf ./report.html ./report.pdf

For multiple input pages, pass each input followed by the output file:

wkhtmltopdf cover.html chapter-1.html chapter-2.html book.pdf

3. Useful command options

List the options available in the installed build:

wkhtmltopdf --extended-help

Common options include:

Need	Example	Notes
Landscape pages	`--orientation Landscape`	Sets the page orientation.
Paper size	`--page-size A4`	Use a named paper size supported by the build.
Margins	`--margin-top 15mm`	Equivalent options exist for right, bottom, and left.
Print background graphics	`--background`	Useful when the design relies on background colors or images.
Wait for JavaScript	`--javascript-delay 2000`	Waits in milliseconds before rendering.
Disable JavaScript	`--disable-javascript`	Can make static pages more predictable.
Cookie	`--cookie name value`	Adds a cookie to the request.
Custom header	`--custom-header Authorization "Bearer …"`	Passes a request header to the page.
Viewport width	`--viewport-size 1280x900`	Changes the browser viewport used for layout.
Quiet output	`--quiet`	Suppresses routine progress output.
Load local files	`--enable-local-file-access`	Required by some local HTML that references local assets; use cautiously.

Review the installed Noble manpage for the exact option set and behavior: Ubuntu 24.04 wkhtmltopdf manpage.

4. Ubuntu’s package versus an upstream build

Ubuntu’s package is the sensible default for Noble because it is built and dependency-managed for that release. Its limitation is that Ubuntu documents it as using unpatched Qt. Upstream’s patched-Qt builds can provide features that distribution builds omit, including some header, footer, and rendering behavior.

Choice	Advantages	Trade-offs
Ubuntu Noble package	Available from Universe; dependencies are handled by APT; packaged for Ubuntu 24.04.	Uses unpatched Qt; behavior can differ from upstream binaries.
Upstream release package	Patched Qt may provide options unavailable in the Ubuntu build.	Upstream lists Jammy (22.04), not Noble; compatibility on every 24.04 host is not guaranteed.

Upstream’s download page lists its supported release builds and explains the older-LTS fallback guidance: wkhtmltopdf downloads. A Jammy package is an older-distribution build, not a Noble-specific guarantee. If you need it, validate library dependencies and PDF output in a disposable or controlled environment before deploying it.

Do not install an unofficial script or third-party package and treat it as an official wkhtmltopdf release. Record the package source and version so production machines can be reproduced.

5. Security limitations

wkhtmltopdf 0.12.6 uses an old Qt/WebKit rendering stack. The upstream project explicitly warns against processing untrusted HTML or JavaScript because malicious input can compromise the server running the renderer. A successful PDF conversion is a functionality check, not a security assurance.

Do not pass user-supplied HTML directly to wkhtmltopdf.
Sanitize and validate HTML, URLs, CSS, and JavaScript before rendering.
Run conversion in a restricted user account or isolated worker.
Limit network access, filesystem access, CPU time, memory, and output size.
Use --disable-local-file-access unless local assets are required.
Never expose a command endpoint that lets users choose arbitrary input URLs.

Read the project’s security and maintenance notes at wkhtmltopdf status. Upstream also points to WeasyPrint or Prince for controlled report HTML and Puppeteer for sites that depend on modern dynamic JavaScript. Those are alternatives to evaluate for your workload, not drop-in guarantees.

6. Troubleshooting

“Unable to locate package wkhtmltopdf”

Cause: the package index is stale or Universe is disabled.

Fix:

sudo add-apt-repository universe
sudo apt update
apt-cache policy wkhtmltopdf
sudo apt install wkhtmltopdf

“wkhtmltopdf: command not found”

Cause: installation did not finish, or the executable is not on PATH.

Fix:

dpkg -s wkhtmltopdf | grep '^Status'
dpkg -L wkhtmltopdf | grep '/wkhtmltopdf$'
command -v wkhtmltopdf

Reinstall if the package is missing:

sudo apt install --reinstall wkhtmltopdf

Missing shared library or dependency errors

Cause: a package installation was interrupted, or an upstream binary was copied onto Noble without its expected libraries.

Fix: prefer the Noble APT package, then repair interrupted package configuration:

sudo apt update
sudo apt --fix-broken install
sudo dpkg --configure -a
sudo apt install wkhtmltopdf

Blank PDF or “Exit with code 1 due to network error”

Possible causes: DNS or TLS failure, a blocked resource, a page that requires authentication, JavaScript that has not finished, or a site that rejects the old browser user agent.

Fixes:

Test the URL with curl -I from the same host.
Try a controlled static page to separate installation problems from site problems.
Add a bounded --javascript-delay for pages that finish rendering asynchronously.
Supply required cookies or headers with --cookie and --custom-header.
Check the command’s diagnostic output without --quiet.

Headers, footers, or modern CSS do not render

Cause: the Ubuntu build uses unpatched Qt and an old WebKit engine.

Fix: confirm whether the needed option appears in wkhtmltopdf --extended-help. If the feature requires patched Qt, evaluate an upstream build in a controlled environment or choose a maintained renderer suited to the page.

Local images, CSS, or fonts are missing

Cause: local file access is restricted, paths are relative to an unexpected directory, or the renderer cannot access the asset.

Fix: use absolute paths, verify permissions, and only when necessary add:

wkhtmltopdf --enable-local-file-access ./report.html ./report.pdf

Fonts differ between machines

Cause: the required font is not installed or the renderer uses a different font fallback.

Fix: install the approved fonts on the worker, verify with fc-match, and keep the rendering environment consistent.

7. Automation and reliability

For repeatable jobs, pin the Ubuntu image and package version, record the output of wkhtmltopdf --version, and keep input HTML and assets deterministic. Use a temporary output path and rename the file only after the process exits successfully:

set -eu
out="/tmp/report.pdf.part"
wkhtmltopdf --quiet https://example.com "$out"
test -s "$out"
mv "$out" /tmp/report.pdf

Run independent conversions in separate worker processes and impose an external timeout. A page can hang while waiting for a resource or script; a shell-level timeout prevents one job from consuming a worker indefinitely:

timeout --signal=TERM 120s wkhtmltopdf https://example.com /tmp/example.pdf

Capture stderr and the exit code in your job system. Retry only transient network failures, and avoid retrying malformed HTML or deterministic rendering errors. If output correctness matters, validate that the PDF exists, is non-empty, and can be opened by your downstream PDF parser.

8. Performance and cost considerations

Rendering time depends on page size, network resources, JavaScript delays, fonts, images, and the number of pages.
Use a bounded delay rather than an unnecessarily large fixed wait.
Cache stable inputs and assets where your application can do so safely.
Limit concurrency to the CPU and memory available to the worker host.
APT installation itself is free; your operational costs are the host, storage, network traffic, and worker time.
The old WebKit engine may require workarounds for modern sites, increasing maintenance cost.

Or skip the browser setup

ScreenshotNeo provides a website screenshot API when you need an image or PDF without maintaining a browser installation. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for all options.

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

import requests

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

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const body = Buffer.from(await res.arrayBuffer());
await fs.promises.writeFile('shot.webp', body);

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. It also offers an MCP server so Claude, Cursor, and other MCP clients can call take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

9. FAQ

Is wkhtmltopdf available for Ubuntu 24.04?

Yes. Ubuntu Noble publishes 0.12.6-2build2 in Universe for amd64.

Should I use `dpkg -i` to install it?

Use APT first. APT resolves dependencies; dpkg does not.

Does the Ubuntu package include patched Qt?

No. Ubuntu’s Noble manpage identifies the build as using unpatched Qt.

Can wkhtmltopdf render any modern website?

No. It uses an old WebKit engine. JavaScript-heavy sites and modern CSS may need a different renderer.

Is a successful PDF proof that the input was safe?

No. Keep untrusted HTML and JavaScript away from wkhtmltopdf, even when conversion succeeds.