You can run wkhtmltopdf without installing it system-wide by packaging a build for the server’s operating system and CPU architecture, extracting it into your application directory, and invoking its executable by an explicit path. You must also supply any missing runtime libraries, fonts, and font configuration. Test the bundle in the same operating-system image and architecture used in production: “static” wkhtmltopdf builds still depend on system components, and a Linux binary built for one libc or distribution may not run on another.
What “without installing” means
It means avoiding a system-wide package installation, not removing the renderer’s runtime requirements. Your deployment artifact can contain the wkhtmltopdf executable and the libraries, configuration, and fonts it needs. Your application then runs that copy directly, rather than relying on a binary installed in a shared system path such as /usr/bin.
wkhtmltopdf is a headless command-line renderer: it turns HTML into PDF using Qt WebKit and does not need a display service. The project’s basic invocation is wkhtmltopdf http://google.com google.pdf. In an application deployment, replace the command name with the full path to the packaged executable.
This approach is useful on restricted hosts, immutable deployments, and function runtimes where you can deploy application files but cannot install operating-system packages. It does not make one binary portable across every Linux server.
Recommended Free Tools
#1 Best Overall
Choose a bundle that matches the target runtime
Start with the environment where the program will actually run—not the workstation or build machine. Match the package to the target distribution and release, CPU architecture, and C library. A package that works on the builder may still fail in production if those differ.
Check the project’s release and package
The wkhtmltopdf downloads page lists 0.12.6 as the stable series and dates its release to June 11, 2020. The packaging releases include a 0.12.6.1-3 release with assets for multiple distributions and architectures, as well as a separate 0.12.6 Lambda release. These labels do not establish compatibility with every current host: inspect the actual release asset and confirm that its target matches your deployment runtime before packaging it.
The project FAQ explains that “static” refers to Qt being statically linked. Other system packages can still be required. In particular, differences in libc, OpenSSL, and other libraries have made generic Linux binaries unreliable across distributions. Alpine uses musl, and the project FAQ says its generic binaries never really worked there. Do not assume an arbitrary Linux build will run on Alpine.
Keep fonts and font configuration with the renderer
A binary can start and still produce poor output if fontconfig, freetype2, the expected fonts, or their configuration are unavailable. Missing fonts may be substituted, changing line breaks, pagination, and document appearance. Package the font runtime and fonts required by your documents, and test representative output in the target image.
Package and invoke wkhtmltopdf from your application
- Identify the production target. Record the operating-system distribution and version, architecture, and—on Linux—the relevant libc environment. Select an upstream package built for that target. Do not choose solely by the phrase “Linux” or “static.”
- Extract the package into the deployment artifact. Keep it in a directory owned by the application, for example
vendor/wkhtmltopdf. For a Debian package, the extraction pattern isdpkg-deb -x "$WKHTML_PACKAGE" "$APP_DIR/vendor/wkhtmltopdf"; setWKHTML_PACKAGEto the selected package file andAPP_DIRto the application directory in your build environment. Extraction avoids registering a system package, but does not install or supply all dependencies automatically. - Locate the executable and inspect dependencies. Package layouts vary, so find the actual binary under the extracted directory rather than assuming its location. On Linux, use
lddon that binary in a compatible environment to identify shared libraries that are not found. Include the required libraries and any relevant font files and configuration in the deployment artifact. - Set runtime paths where needed. If the bundled libraries are outside the loader’s standard paths, configure
LD_LIBRARY_PATHfor the process to include their actual directory. Configure fontconfig to use the bundled configuration and fonts where necessary; its environment variable isFONTCONFIG_PATH. The correct directories depend on the package layout, so do not copy a path from another distribution without checking it. - Call the executable by full path. Set your application’s renderer path to the extracted binary, then invoke it with the input and output arguments your application needs. Avoid relying on
PATHto happen to resolve a system-installed copy. - Test in the deployment image. Run
/path/to/your/bundled/wkhtmltopdf --versionas a basic executable check, then render a representative document locally in that same runtime. Check fonts, images, headers and footers, page size, margins, and any JavaScript-dependent content. A successful version check alone does not establish that your real documents will render correctly.
The /path/to/your/bundled/wkhtmltopdf text above represents the executable path you found in your extracted package; it is not a universal package location. The project’s CLI manual documents --version as a supported option.
Use a container when you need a separate runtime
If the host can run containers, place the renderer, compatible operating-system libraries, and fonts in a dedicated image and invoke it through a controlled interface. Pass input and output files through an appropriately restricted mounted directory or another application-controlled boundary. The container reduces dependence on the host’s installed libraries; it does not make an incompatible binary compatible or guarantee identical rendering without testing.
Choose the container’s base operating system with the selected wkhtmltopdf build in mind. In particular, do not use Alpine as a drop-in base for an arbitrary upstream Linux binary: its musl environment differs from glibc-based distributions. Keep the renderer’s package and its runtime environment together, and verify the result with the same representative documents used in production.
Use the documented Lambda bundle or layer
The wkhtmltopdf FAQ describes a Lambda zip package built for Amazon Linux 2. It can be included with the function or deployed as a layer. The FAQ’s example uses these paths and environment settings:
Best Value
LD_LIBRARY_PATH=/opt/lib
FONTCONFIG_PATH=/opt/fonts
/opt/bin/wkhtmltopdf input.html output.pdfFor a Lambda deployment using that bundle, retain the FONTCONFIG_PATH=/opt/fonts setting in the function environment, as the FAQ directs. The paths are specific to that documented package; they are not defaults for every extracted wkhtmltopdf build. The release list also identifies a Lambda-specific 0.12.6 r4 package. Confirm that the selected package’s runtime operating system matches the Lambda runtime you deploy rather than assuming an older bundle will fit an arbitrary current runtime.
Security and maintenance limits matter
Running the executable from your application directory does not make rendering untrusted HTML safe. The project status page warns: “Do not use wkhtmltopdf with any untrusted HTML – be sure to sanitize any user-supplied HTML/JS, otherwise it can lead to complete takeover of the server it is running on!” Treat input as a security boundary: sanitize user-supplied HTML and JavaScript, and consider operating-system isolation controls such as AppArmor or SELinux. A container is not, by itself, a substitute for input controls or process isolation.
The same status page notes that Qt 4 has not been supported since 2015 and its WebKit has not been updated since 2012. The main GitHub repository was archived and made read-only on January 2, 2023. Packaging releases may still provide assets, but they do not update the old rendering engine or remove the security concerns. If your workload needs modern JavaScript, the project maintainer suggests Puppeteer or a wrapper; for application-controlled report HTML, the maintainer suggests considering WeasyPrint or commercial Prince. Those are workload-based suggestions, not benchmark claims.
Troubleshoot common deployment failures
- “No such file or directory” even though the binary exists: On Linux, this can indicate that the executable’s expected loader or a required library is missing, not merely that the file path is wrong. Check the full path, run
lddin the target environment, and include compatible missing dependencies. - “Shared library not found” or a loader error: The bundle is incomplete or the loader cannot find a bundled library. Add the matching library to the deployment artifact and set
LD_LIBRARY_PATHto its actual directory for the renderer process. - It works in one image but not another: Compare distribution, release, architecture, libc, and library versions. Select a package made for the deployment target and reproduce the test in that image; do not infer broad portability from one successful host.
- Alpine fails to launch a generic Linux build: The libc environment may be the mismatch. The project FAQ specifically cautions that its generic binaries did not really work on Alpine. Use a build/package appropriate for the actual target instead of assuming glibc compatibility.
- PDFs have substituted fonts or changed pagination: Check fontconfig, freetype2, installed fonts, and
FONTCONFIG_PATH. Compare a representative document in the final deployment image, where the application will actually render it. - The version command succeeds but a document fails or looks different:
--versionchecks that the executable can report its version; it does not test the document’s assets, fonts, JavaScript behavior, or layout. Test the exact rendering path and inspect the input/output environment. - User-controlled HTML is being rendered: Treat this as a security issue, not a packaging issue. Sanitize supplied HTML/JavaScript and isolate the renderer process; consult the project status page’s warning before exposing it to untrusted content.
Or skip the browser setup
If the goal is to capture a public webpage as an image or PDF rather than run wkhtmltopdf against application-controlled HTML, ScreenshotNeo offers a hosted API. It is not a drop-in wkhtmltopdf binary and does not render a local HTML file. One GET request with a URL returns a screenshot or PDF; see the ScreenshotNeo API documentation.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsQuick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, and cache hits are not billed. Its MCP server lets AI agents use screenshot tools, and the free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. See ScreenshotNeo for the service and sign up free.
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.
