How to Fix the libwkhtmltox Shared Library Loading Error

Direct fix: copy the exact shared-object name from the error, locate that file, install the runtime package that provides it or add its private directory to the dynamic loader path, refresh the loader cache when needed, and rerun wkhtmltopdf. If another SONAME appears, resolve that dependency too.

The first error often names libwkhtmltox.so.0, but wkhtmltopdf can also fail on libfontconfig.so.1, libQt5Core.so.5, libXrender.so.1, libXext.so.6 and related font or X11 libraries. The named SONAME is your most useful diagnostic clue.

1. Read the loader error precisely

A message such as:

error while loading shared libraries: libwkhtmltox.so.0: cannot open shared object file: No such file or directory

comes from the Linux dynamic linker before wkhtmltopdf can run. It means the linker could not resolve the named shared object in its configured search paths. It does not always mean the file is absent; a private bundle may contain it while its directory remains invisible to the loader.

2. Check whether the library exists

Start with the exact SONAME from the error. Replace the example name below with the one you received.

missing='libwkhtmltox.so.0'

# Search common system and application locations
find /usr /lib /lib64 /opt /app -name "$missing" -type f 2>/dev/null

# Ask the loader cache whether it knows the file
ldconfig -p 2>/dev/null | grep -F "$missing" || true

Interpret the result:

Result	Meaning	Next step
No result	The file is absent from searched locations.	Install the distribution runtime package or add the complete private bundle.
File under `/opt`, `/app` or another private directory	The binary may not search that directory.	Set `LD_LIBRARY_PATH` for the process.
File under a standard library directory but `ldconfig` does not list it	The loader cache is stale or the directory is not configured.	Configure the directory and run `sudo ldconfig`.

3. Install the runtime dependency

When the SONAME is absent, install the operating system package that provides it. Use runtime packages, not only development headers. The package name depends on the distribution, release, CPU architecture and wkhtmltopdf build.

Font errors such as libfontconfig.so.1 require the distribution’s fontconfig runtime and usually usable fonts.
Qt errors such as libQt5Core.so.5 require the matching Qt runtime for the build you installed.
X11 errors such as libXrender.so.1 or libXext.so.6 require the corresponding X11 runtime libraries.

Do not copy an Ubuntu package name into Alpine, an RPM based image or a different architecture. Query the target repository for the SONAME, then install the package from that repository. Confirm the downloaded wkhtmltopdf binary matches the target libc and architecture.

4. Make a private bundle visible with LD_LIBRARY_PATH

For a self contained wkhtmltopdf distribution, point the loader at the directory containing its libraries:

LD_LIBRARY_PATH=/opt/wkhtmltox/lib \
  /opt/wkhtmltox/bin/wkhtmltopdf input.html output.pdf

To inspect all unresolved dependencies before running a conversion:

ldd /opt/wkhtmltox/bin/wkhtmltopdf | grep 'not found' || true
ldd /opt/wkhtmltox/lib/libwkhtmltox.so.0 | grep 'not found' || true

If ldd reports more missing files, add the directories that contain them or install their runtime packages. A chain of different SONAME errors normally means the bundle is incomplete.

For a service, set the variable in the service definition or wrapper rather than relying on an interactive shell:

#!/usr/bin/env bash
set -euo pipefail
export LD_LIBRARY_PATH=/opt/wkhtmltox/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
exec /opt/wkhtmltox/bin/wkhtmltopdf "$@"

5. Refresh the system loader cache with ldconfig

If libraries are installed in a standard location, or you intentionally manage a custom system directory, refresh the cache:

sudo ldconfig
ldconfig -p | grep -E 'libwkhtmltox|libfontconfig|libQt5Core|libXrender'

For a custom directory, add a file such as /etc/ld.so.conf.d/wkhtmltox.conf containing the directory path, then run sudo ldconfig. Use this approach only when you control the host image; LD_LIBRARY_PATH is usually simpler for an application private bundle.

6. Serverless and container deployments

Serverless environments do not inherit libraries from your workstation. Package the distribution specific executable, every required shared library, loader configuration and fonts together. The documented Lambda pattern uses LD_LIBRARY_PATH=/opt/lib and FONTCONFIG_PATH=/opt/fonts.

export LD_LIBRARY_PATH=/opt/lib
export FONTCONFIG_PATH=/opt/fonts
/opt/bin/wkhtmltopdf /tmp/input.html /tmp/output.pdf

Before deployment, run ldd inside the same base image or runtime architecture as production. Check writable paths, executable permissions, temporary storage limits, font availability and the process timeout. A bundle built for x86_64 cannot be assumed to work on arm64, and a glibc binary cannot generally be dropped into a musl based image without a compatible runtime.

7. Diagnose the next failure after the first fix

Run the original command again after each change. If the error changes from libwkhtmltox.so.0 to a Qt, fontconfig or X11 SONAME, the loader has progressed and found the previous dependency. Continue until:

ldd /path/to/wkhtmltopdf | grep 'not found'

prints nothing. Then validate an actual conversion with a minimal document:

cat > /tmp/loader-check.html <<'EOF'
<!doctype html>
<html><body><h1>wkhtmltopdf loader check</h1></body></html>
EOF
/opt/wkhtmltox/bin/wkhtmltopdf /tmp/loader-check.html /tmp/loader-check.pdf
file /tmp/loader-check.pdf

8. Common errors and fixes

Error or symptom	Likely cause	Fix
`libwkhtmltox.so.0` not found	Private library directory is not in the loader path.	Use `LD_LIBRARY_PATH=/path/to/lib` or install the library in a configured system directory.
`libfontconfig.so.1` not found	Fontconfig runtime is missing.	Install the target distribution’s fontconfig runtime and fonts.
`libQt5Core.so.5` not found	Qt runtime does not match the wkhtmltopdf build.	Install the matching Qt runtime or use the vendor bundle built for your distribution.
`libXrender.so.1` or `libXext.so.6` not found	X11 runtime dependency is absent.	Install the corresponding X11 runtime package for the target image.
Works in a shell, fails under systemd, cron or a queue worker	That service does not inherit your shell environment.	Set `LD_LIBRARY_PATH`, `FONTCONFIG_PATH` and `PATH` in the service or wrapper.
Works locally, fails in a container	Different libc, architecture or incomplete image dependencies.	Run `ldd` inside the production image and rebuild for its OS and architecture.
Library exists but still cannot load	Wrong architecture, missing transitive dependency or stale cache.	Run `file` and `ldd` on the binary and library; then refresh `ldconfig` or correct the bundle.
PDF opens with missing glyphs	Fonts are absent even though shared libraries load.	Bundle fonts and set `FONTCONFIG_PATH`; verify font discovery in the runtime.

9. Choosing system packages versus a private bundle

Approach	Best fit	Trade-offs
System runtime packages	Long lived hosts and standard Linux distributions.	Simple updates, but package versions and availability vary by distribution.
Private wkhtmltox bundle	Containers, Lambda and repeatable builds.	Controls versions, but you own every library, font and security update.

Pin the executable and dependency sources in your image build, record the target architecture, and rebuild when the base image or security updates change. Avoid copying random shared objects from another machine; ABI and architecture mismatches create harder failures.

10. Performance and reliability considerations

Resolve libraries at image build time so requests do not fail during a live conversion.
Keep a minimal smoke test in deployment checks that executes wkhtmltopdf and creates a valid PDF.
Reuse a warm process or worker when your integration permits it, but enforce conversion timeouts and clean temporary files.
Package fonts deliberately; missing fonts can produce a successful exit code with incorrect output.
Capture the complete stderr line and the binary version in logs. The first SONAME makes dependency repair much faster.

11. Or skip the browser setup

If your goal is a dependable screenshot or PDF endpoint rather than maintaining wkhtmltopdf libraries, ScreenshotNeo provides a hosted API. It accepts one GET request and returns a PNG, JPEG, WebP or PDF. Cookie and consent banners are accepted and removed before capture, along with more than 60 known consent platforms, newsletter popups and chat widgets. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed.

See the ScreenshotNeo API documentation for all options, including full page capture, CSS element capture, device presets, custom headers and cookies, waiting rules, blocking, PDF settings, caching, signed links, asynchronous jobs, bulk capture and usage reporting.

cURL

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

Python

import requests

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

Node.js

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', data);

Every response identifies the page verdict and billing result with X-Page-Verdict and X-Billed headers. An MCP server also lets Claude, Cursor and other MCP clients call take_screenshot, get_page_info and capture_pdf. The Free plan includes 1,000 screenshots each month without a card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

12. FAQ

Does installing libwkhtmltox alone fix every error?

No. wkhtmltopdf may also need Qt, fontconfig, Xrender, Xext and other transitive runtime libraries.

Should I use LD_LIBRARY_PATH or ldconfig?

Use LD_LIBRARY_PATH for an application private bundle. Use ldconfig when libraries belong in a controlled system directory.

Why does the error name change after I install a package?

The loader has found the previous library and moved to the next unresolved dependency. Repeat the same locate, install or path step.

Can a package extracted from another Linux distribution work?

Only when its architecture, libc, Qt build and transitive dependencies are compatible. Verify with file and ldd in the target runtime.

What must Lambda include?

Include the executable, all required libraries, configuration and fonts, then set the documented library and font paths before invoking wkhtmltopdf.