Recommended Free Tools
Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Fix the error by identifying the exact SONAME named by the dynamic linker, installing the runtime package that provides it, or adding the directory containing a privately bundled library to the loader path. For a system library, run sudo ldconfig after installation. For a bundled wkhtmltopdf build, launch it with LD_LIBRARY_PATH. If the next run reports another missing object, resolve that dependency too; the messages form a dependency chain.
What the message means
Linux programs do not contain every library they use. At startup, the dynamic linker searches configured system directories and any paths supplied by the process. A message such as error while loading shared libraries: libwkhtmltox.so.0: cannot open shared object file: No such file or directory means the linker could not resolve that shared object before wkhtmltopdf could start.
The filename is a SONAME, and it is your first diagnostic clue. Depending on the build and operating system, the missing name may instead be libfontconfig.so.1, libQt5Core.so.5, libXrender.so.1, libXext.so.6, or another Qt, font, or X11 library. Do not install packages at random: copy the exact name from the error and investigate that object first.
Diagnose the missing library before changing the system
1. Capture the exact SONAME
Copy the complete error, including capitalization and the suffix after .so. libfontconfig.so.1 is not interchangeable with a similarly named development file or a different ABI version.
#1 Best Overall
2. Check the executable and private bundle
Find the binary you are actually invoking:
command -v wkhtmltopdf
readlink -f "$(command -v wkhtmltopdf)"
Then inspect its direct dependencies:
ldd "$(command -v wkhtmltopdf)" | grep -E 'not found|wkhtml|fontconfig|Qt|Xrender|Xext'
If you extracted a vendor archive, inspect its directories as well:
find /opt/wkhtmltox -type f ( -name '*.so' -o -name '*.so.*' ) -print
A file can exist in the bundle and still be invisible to the loader. “No such file” therefore has two common meanings: the object is absent, or its directory is not on the search path.
3. Inspect what the binary requests
readelf -d "$(command -v wkhtmltopdf)" | grep NEEDED
This shows the names embedded in the executable. Use it together with ldd to distinguish a missing direct dependency from a transitive dependency required by Qt or another library.
Choose a repair strategy
| Approach | Use it when | Advantages | Trade-offs |
|---|---|---|---|
| Distribution runtime packages | The host is a normal, supported Linux installation and repositories match its architecture. | Package updates, security ownership, and integration with the system loader are straightforward. | Package names and ABI versions vary by distribution; an upgrade can change the available libraries. |
| Private wkhtmltox bundle | You need repeatable deployment, a pinned build, or a restricted/serverless runtime. | You control executable, library, configuration, and font versions together. | You own patching and must package every transitive dependency and compatible font. |
Do not copy an Ubuntu package name to Alpine, an RPM-based distribution, or a different CPU architecture. Resolve the SONAME using the target distribution’s current repository metadata and verify that the downloaded binary matches the target ABI.
Fix a system installation
Install the runtime provider
Use your distribution’s package search to map the SONAME to a runtime package. Install the runtime package, not only a development package: headers and linker files in a -dev or -devel package do not guarantee that the runtime object is installed.
Dependency families commonly involved with wkhtmltopdf include fontconfig, Qt, Xrender, and Xext. The exact package names differ by release and architecture, so check the repository for your specific host. After installation, verify the file and its architecture:
find /usr/lib /usr/lib64 /lib /lib64 -name 'libfontconfig.so*' 2>/dev/null
file /path/to/the/library.so
Rebuild the dynamic-linker cache
When the library is in a configured system directory, update the cache:
sudo ldconfig
ldconfig -p | grep -E 'libwkhtmltox|libfontconfig|libQt5Core|libXrender|libXext'
ldconfig creates the expected symbolic links and cache entries from configured and trusted library directories. If the directory is non-standard, add it through your distribution’s loader configuration, then run sudo ldconfig again. Avoid permanently exporting a broad library path that could make unrelated programs load incompatible versions.
Retry and follow the dependency chain
wkhtmltopdf input.html output.pdf
If a new SONAME appears, repeat the same process. Several successive errors normally mean the original installation has an incomplete dependency set; they are not evidence that the first repair made the problem worse.
Fix a private or extracted wkhtmltox bundle
The official downloads guidance allows extraction when a package cannot be installed, but extraction does not supply missing operating-system dependencies automatically. Keep the executable, its libraries, configuration files, and fonts in a known directory.
Run with LD_LIBRARY_PATH
If libwkhtmltox.so.0 is under /opt/wkhtmltox/lib, launch the program like this:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →LD_LIBRARY_PATH=/opt/wkhtmltox/lib /opt/wkhtmltox/bin/wkhtmltopdf input.html output.pdf
This changes the loader path for that process only. It is safer than replacing system libraries globally, and it is the appropriate pattern when a bundled library is present but invisible.
Confirm every bundled dependency
LD_LIBRARY_PATH=/opt/wkhtmltox/lib
ldd /opt/wkhtmltox/bin/wkhtmltopdf | grep 'not found'
An empty result means the loader can resolve the libraries visible through that path. If a system dependency remains missing, install it in the host image or include a compatible copy in the bundle. Never mix libraries built for a different CPU architecture or incompatible C library.
Make the launch repeatable
Use a wrapper rather than relying on an interactive shell:
#!/bin/sh
set -eu
export LD_LIBRARY_PATH=/opt/wkhtmltox/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
exec /opt/wkhtmltox/bin/wkhtmltopdf "$@"
Test the wrapper under the same service account, working directory, environment, and filesystem permissions used in production. A command that works in an administrator shell can fail for a web worker because its environment and readable font directories differ.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11AWS Lambda and other serverless runtimes
Serverless packaging must include the distribution-specific executable, all required libraries, configuration, and fonts. A binary copied into a layer without its Qt, fontconfig, X11, or font resources will still fail at startup.
Best Value
The Lambda configuration pattern documented for wkhtmltopdf uses:
LD_LIBRARY_PATH=/opt/lib
FONTCONFIG_PATH=/opt/fonts
Place shared objects in /opt/lib and fonts/configuration in /opt/fonts, then set both variables in the function environment or wrapper. Validate the layer inside the actual Lambda runtime image, not only on your workstation. Check:
- The executable and every shared object target the Lambda architecture, such as x86_64 or arm64.
- The files are executable or readable as appropriate and are not hidden by an incorrect layer path.
- Fontconfig can read its configuration and at least the fonts your documents require.
ldd(or an equivalent inspection method available in the build image) shows no unresolved objects.- The temporary output directory is writable and the process does not assume a desktop display server.
For other restricted containers, apply the same principle: package the complete runtime and set paths explicitly. Do not assume a package extracted on one distribution is binary-compatible with another.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsCommon symptoms and targeted fixes
| Symptom | Likely cause | Action |
|---|---|---|
libwkhtmltox.so.0 is missing, but the file is visible in your archive. |
The private library directory is absent from the loader path. | Use LD_LIBRARY_PATH=/path/to/lib wkhtmltopdf ... and verify with ldd. |
libfontconfig.so.1 is missing. |
Fontconfig runtime package or compatible bundled library is absent. | Install the target distribution’s runtime provider, then run ldconfig, or package a compatible runtime copy and fonts. |
libQt5Core.so.5 or another Qt object is missing. |
The wkhtmltopdf build’s Qt runtime was not installed or does not match the host. | Install the matching Qt runtime family or use a complete, architecture-compatible bundle. |
libXrender.so.1 or libXext.so.6 is missing. |
An X11 rendering runtime dependency is absent, even on a headless server. | Install the corresponding runtime package for the target distribution or bundle it with the binary. |
| The error changes after each fix. | Dependencies are resolved sequentially. | Repeat the SONAME workflow until ldd reports no “not found” entries. |
| It works manually but fails from a service. | Different environment, user permissions, working directory, or font paths. | Use an explicit wrapper and test as the service account with production paths. |
Reliability, security, and maintenance
- Pin the build: Record the wkhtmltopdf version, operating-system release, architecture, and library package versions used to create the image or layer.
- Patch ownership: System packages receive updates from the distribution; private bundles require your team to monitor and replace vulnerable libraries.
- Limit path scope: Prefer a per-process
LD_LIBRARY_PATHor a dedicated wrapper over a global shell profile change. - Reproduce the environment: Build and test in the same container or Lambda base image used in production.
- Keep fonts deliberate: Missing fonts can produce incorrect PDFs even after the loader error is fixed. Package the fonts and fontconfig configuration your documents require.
- Observe startup separately from rendering: A clean process launch proves libraries resolve; it does not prove that every page, image, JavaScript feature, or font renders correctly.
Or skip the browser setup
If your actual goal is generating a clean website screenshot or PDF rather than maintaining wkhtmltopdf, ScreenshotNeo provides a hosted screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF without packaging Qt, X11, fontconfig, or Lambda layers.
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)
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}`);
See the ScreenshotNeo documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before the shot; bot checks, blank pages, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server lets AI agents take screenshots, inspect pages, and capture PDFs. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Frequently Asked Questions
Why does installing a development package not fix the error?
Development packages primarily provide headers and linker metadata. wkhtmltopdf needs the runtime shared object at execution time, so install the distribution package that actually contains the SONAME named in the error.
Should I copy a missing .so file from another server?
Only when it was built for the same distribution ABI, CPU architecture, and compatible dependency set. Otherwise use the target repository or a complete bundle; an isolated copied file can create harder-to-diagnose symbol or version failures.
Is LD_LIBRARY_PATH required when libraries are installed in /usr/lib?
Normally no. Standard directories are covered by the dynamic-linker configuration. Run sudo ldconfig after installation and reserve LD_LIBRARY_PATH for private or non-standard library directories.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
