The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To run wkhtmltopdf on AWS Lambda, deploy a Linux-compatible executable together with every required shared library and font, then invoke it from your function. The two practical packaging choices are a ZIP deployment with a Lambda layer or a Lambda container image. In either case, build and test for the Lambda operating-system generation and CPU architecture you actually deploy; a binary that works on a developer machine is not evidence that it will run in Lambda.
This guide covers the packaging decisions, a reproducible layer layout, container-image considerations, validation, common failures, and an alternative for screenshot-only jobs.
Why wkhtmltopdf needs extra packaging on Lambda
wkhtmltopdf converts HTML to PDF using WebKit (QtWebKit). It is a native executable, not a pure application-library dependency, so Lambda does not provide it automatically. Your deployment must make the executable, its dynamic libraries, and the fonts it needs available at runtime.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
A typical failure is a missing shared library: the executable starts, but the target environment cannot resolve one of its dependencies. A second common issue is font discovery: the PDF is produced, but text uses an unexpected fallback or glyphs are absent because the expected fonts or font configuration are missing.
#1 Best Overall
There is no universally valid binary or layer established for every Lambda runtime and architecture. Match and test the complete package against the runtime you select.
Choose ZIP plus layer or a container image
| Choice | Where dependencies live | Best fit | Update responsibility |
|---|---|---|---|
| ZIP function package plus Lambda layer | The function code is in the deployment ZIP; the layer ZIP supplies shared executable and dependency files under /opt. |
You want to reuse the same native package across functions or keep application code separate from system dependencies. | You build and publish compatible layer versions, then attach the required version to each function. |
| Lambda container image | The executable, libraries, fonts and application are included in the image. | You want to control the full filesystem and build all dependencies together. | You rebuild and redeploy the image when its base image or bundled dependencies need updates. |
AWS documents both deployment approaches. Its Lambda base images include Amazon Linux system libraries and a runtime interface client; they do not thereby include wkhtmltopdf. AWS manages managed-runtime updates, while image users are responsible for rebuilding from updated base images and redeploying.
Plan for the runtime and architecture first
Choose the Lambda runtime identifier and architecture before acquiring or building the converter. AWS documents x86_64 and arm64, but that does not mean a single native build works on both. A community AL2023 layer example discussed below defaults to x86_64; treat that as a constraint of that example, not a Lambda-wide guarantee.
AWS states that Amazon Linux 2 reached end of life on June 30, 2026, and recommends moving to AL2023-based runtimes. Check the current AWS runtime support table when selecting a runtime; AWS labels projected deprecation dates as forecasts that can change.
Build a ZIP layer with the executable and dependencies
For a layer, arrange files so Lambda can find them after extracting the layer. AWS documents that layer contents are loaded into /opt; it recognizes bin for PATH and lib for LD_LIBRARY_PATH across runtimes. An example layout is:
layer-root/
bin/
wkhtmltopdf
lib/
# Required shared libraries not present in the target runtime
fonts/
# Fonts your generated PDFs need
etc/
fonts/
fonts.confWith this layout, your function can call /opt/bin/wkhtmltopdf. A wrapper script can set library and font paths before starting the executable. Ensure the executable bit survives packaging, and verify that every library named by the executable resolves in the deployed environment.
Rank #3
Build in a compatible Linux environment
- Fix the deployment target. Record the Lambda runtime operating-system generation and architecture selected in your function configuration.
- Build or assemble in Linux for that target. AWS recommends building layer content in a Linux environment and suggests Docker as a way to create one. Avoid assuming a macOS or Windows executable and its libraries will run on Lambda.
- Collect dependencies deliberately. Inspect dynamic dependencies in the build environment, identify libraries absent from the target runtime, and package those libraries in the layer. Do not copy a dependency list from a different OS generation without checking it.
- Configure fonts. Include fonts needed by your documents and make fontconfig locate them. A community AL2023 example packages DejaVu fonts and points fontconfig at the bundled files; its exact package set is an example to validate, not an AWS recipe.
- Preserve permissions and paths. Confirm the executable is executable in the ZIP and that the final paths correspond to
/opt/bin,/opt/lib, and your chosen font directory. - Smoke-test the artifact. Run the packaged executable in a container matching the Lambda runtime and architecture, or test in a function with those settings, and inspect the resulting PDF.
A community example describes an AL2023 approach using an AlmaLinux 9 RPM and font/graphics dependencies. Its repository also describes inspecting dependencies with ldd and comparing against an AL2023 Lambda image. Those details are a starting point for investigation, not an official compatibility promise or proof that a bundled RPM is safe for your workload. Validate provenance, library resolution, fonts, and output in your own target environment.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Invoke the layer from function code
Use an absolute path so invocation does not depend on the process PATH. This Python handler illustrates the invocation pattern; it assumes the layer has already placed the executable and dependencies where shown, and that the input HTML file exists at /tmp/input.html.
import subprocess
WKHTMLTOPDF = "/opt/bin/wkhtmltopdf"
def handler(event, context):
source = "/tmp/input.html"
destination = "/tmp/output.pdf"
result = subprocess.run(
[WKHTMLTOPDF, source, destination],
capture_output=True,
text=True,
check=False,
)
if result.returncode != 0:
raise RuntimeError(
f"wkhtmltopdf exited {result.returncode}: {result.stderr}"
)
with open(destination, "rb") as pdf:
return {
"statusCode": 200,
"headers": {"content-type": "application/pdf"},
"body": pdf.read().hex(),
}This example returns the PDF bytes encoded as hexadecimal only to keep the handler self-contained; that is not a recommended general API transfer format. For an HTTP response, use the response mechanism and binary handling appropriate to your integration. For larger PDFs, store the file in durable object storage and return a reference rather than putting the document in a function response. Lambda’s writable temporary directory is /tmp; keep intermediate files there rather than assuming the function package is writable.
Package wkhtmltopdf in a Lambda container image
With a container image, install or copy the executable, compatible shared libraries, fonts, and font configuration into the image. Start from an AWS Lambda base image appropriate to the function runtime, and make sure the image targets the same CPU architecture configured for the function. Do not infer compatibility merely because the image builds successfully: the binary must run in that image and render the required documents correctly.
Build the image in a repeatable process that pins and records its inputs. Verify the resolved libraries and font lookup during the image build or in a test run. Since image users maintain and redeploy their images, include base-image refreshes and dependency updates in the deployment process.
Validate the package before production
- Executable check: confirm the file exists at the invocation path and has executable permissions.
- Architecture check: confirm the binary and all native libraries match the configured Lambda architecture.
- Library check: run a dependency inspection in the target-like Linux environment and resolve any missing library there, not just on the build host.
- Font check: render a test document with the fonts and non-ASCII characters your workload uses; inspect the PDF, not merely the process exit code.
- Network and input check: if the HTML references remote assets, test whether those resources are reachable from the function and whether the generated PDF behaves acceptably when they are unavailable.
- Operational check: test realistic input sizes and duration against the configured Lambda timeout and memory. No performance benchmark for this combination is established here, so measure your own documents.
Keep the test artifact and deployment artifact identical. Testing a separately installed system package does not validate the ZIP or image that Lambda will actually execute.
Best Value
Troubleshoot common failures
| Symptom | Likely cause | What to check or change |
|---|---|---|
No such file or directory when launching an existing executable |
The path is wrong, or the executable’s expected loader is absent in the target environment. | Check the exact absolute path and inspect the binary in a matching Linux image. Confirm the target runtime has the needed loader. |
error while loading shared libraries |
A required native library is missing or outside the runtime search path. | Inspect dependencies in the target-like environment, package missing libraries, and ensure they are under a path such as /opt/lib that Lambda exposes through LD_LIBRARY_PATH. |
Permission denied |
The executable bit was lost, or the file is being run from an unsuitable path. | Preserve executable permissions in the build and ZIP process; invoke the deployed file under /opt/bin. |
Exec format error |
The binary architecture does not match the function architecture, or it is not a compatible Linux executable. | Rebuild or obtain a binary for the selected Lambda OS family and architecture; test it in the corresponding environment. |
| PDF renders with substituted fonts, missing glyphs, or odd spacing | Fonts are not bundled or fontconfig cannot find them. | Include the required fonts and valid font configuration, then test the actual characters and layouts in your documents. |
| The process times out or exits unsuccessfully on some pages | Rendering, remote asset loading, or input complexity exceeds what the function’s current settings allow. | Capture stderr and exit status, test with a minimal local HTML file, then isolate external assets and measure realistic inputs against the configured timeout and memory. |
Or skip the browser setup
If your requirement is a website screenshot rather than a PDF created from arbitrary HTML, a screenshot API avoids packaging and operating a browser binary in Lambda. ScreenshotNeo is a website screenshot API and MCP server; it accepts a URL in one GET request and can return PNG, JPEG, WebP, or PDF. It accepts cookie/consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture, with each step independently switchable. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status.
Example cURL request (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.webpScreenshotNeo also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. This is a different job from running wkhtmltopdf on your own HTML: choose it when URL capture and its returned image or PDF fit the task.
Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Does AWS Lambda include wkhtmltopdf?
No. Package a compatible executable, its required shared libraries, and fonts in your deployment.
Can the same wkhtmltopdf layer run on x86_64 and arm64?
Do not assume so. Build and validate a package for the function’s configured architecture.
Is the community AL2023 layer an official AWS package?
No. It is an example implementation and must be validated for your runtime, architecture, dependencies, and document output.
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 & 11Quick 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.
