Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Short answer: install an Alpine-built wkhtmltopdf package that matches your Alpine branch and CPU architecture, verify its Qt build and shared libraries in the final container, then invoke the executable from Python 3.6 as a subprocess. Do not copy a generic Linux binary: Alpine uses musl libc, while many upstream downloads target glibc. The historical package records available for this topic do not establish a currently supported Python 3.6 and Alpine combination, so treat every version as something to verify against your image.
Why Alpine needs a different wkhtmltopdf plan
wkhtmltopdf is an operating-system executable. Python 3.6 does not install it; your application starts the binary and reads its exit status, output and errors. Alpine Linux uses musl libc. The wkhtmltopdf project’s FAQ explains that generic Linux binaries did not work on Alpine for this reason. Use an Alpine package or a build made for your exact target rather than assuming a download labelled “Linux” will run.
There is a second compatibility issue: Qt. wkhtmltopdf’s project describes patched Qt as providing rendering features that upstream Qt lacks. A historical Alpine container example described an unpatched package and replaced it with a patched-Qt binary. Whether that matters depends on your HTML, CSS, JavaScript and pagination requirements; a binary that starts can still produce incorrect PDFs.
Before installing: identify the target precisely
Run these checks inside the image you will ship:
cat /etc/alpine-release
uname -m
python3 --version
apk policy wkhtmltopdf || true
cat /etc/apk/repositories- Branch: record the exact Alpine release, not merely “Alpine.” Repository contents differ by branch.
- Architecture: common values include
x86_64andaarch64. A package for one cannot be used as evidence for the other. - Python constraint: Python 3.6 is end-of-life. Keep it only when your application requires it, and isolate the image and network exposure accordingly.
- Repositories: confirm that the repositories configured for this branch actually contain
wkhtmltopdf.
Option 1: install the repository package
If your configured repositories offer a package for the exact branch and architecture, install it with:
apk add --no-cache wkhtmltopdfThe Alpine package index records a historical wkhtmltopdf 0.12.6-r0 build for Alpine v3.14 on x86_64. That row is evidence of availability for that branch and architecture in 2020, not proof that a current image has the same package. Check the result of apk policy and the package metadata before proceeding.
Inspect dependencies and linkage
apk info -a wkhtmltopdf
command -v wkhtmltopdf
wkhtmltopdf --version
ldd "$(command -v wkhtmltopdf)"Review missing-library messages from ldd and package metadata. Fontconfig and freetype are specifically relevant to wkhtmltopdf rendering. A binary described as static can still rely on system fonts or other non-Qt libraries. Install only the libraries required by your chosen package and verify them in the final image, rather than copying dependency pins from an old container recipe.
Option 2: use a compatible Alpine build
If the repository has no suitable package, choose a reproducible Alpine build for your branch and architecture, or build wkhtmltopdf yourself. Establish these acceptance criteria before selecting an artifact:
- It was built for your Alpine branch and CPU architecture.
- Its Qt build supplies the patched behavior your documents need.
- Its complete runtime closure, including fonts, exists in the final image.
- You can retain provenance, checksums and a rebuild process.
Do not treat the historical Alpine v3.9 archive as a current recipe. It contains a wkhtmltopdf 0.12.5-r0 artifact dated 27 December 2018 and Python 3.6.8 artifacts dated 24 January 2019, including aarch64 files. It does not show that those packages were installed together, work on x86_64, or remain appropriate today.
Recommended Free Tools
Patched Qt is a functional choice
Compare output, not just --version. Create a fixture containing web fonts, images, JavaScript, page breaks, headers and footers, then render it in the final container. Inspect the PDF for missing glyphs, blank images, incorrect pagination and JavaScript timing. If your application depends on capabilities associated with patched Qt, an unpatched package may be unsuitable even when installation succeeds.
Validate the executable in the final image
- Run
wkhtmltopdf --versionand save the exact output with your build record. - Check
lddfor unresolved libraries. - Verify that fontconfig and freetype can see the fonts you require. Add a known font package if your document needs glyphs absent from the base image.
- Render a representative local file and a representative permitted URL:
printf '<html><body><h1>Alpine test</h1><p>A—文—🙂</p></body></html>' > /tmp/test.html
wkhtmltopdf /tmp/test.html /tmp/test.pdf
file /tmp/test.pdfRun this test under the same user, working directory, environment and network policy used by Python. A successful local conversion does not prove that remote assets, DNS, TLS, authentication or JavaScript will work.
Call wkhtmltopdf from Python 3.6
Use subprocess.run with an argument list, a timeout and captured stderr. Avoid shell=True; it makes URL or filename injection easier.
import subprocess
from pathlib import Path
def html_to_pdf(source, destination, timeout=90):
cmd = [
"wkhtmltopdf",
"--quiet",
source,
destination,
]
try:
result = subprocess.run(
cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
timeout=timeout, check=False
)
except FileNotFoundError:
raise RuntimeError("wkhtmltopdf is not installed or not on PATH")
except subprocess.TimeoutExpired:
raise RuntimeError("wkhtmltopdf exceeded its timeout")
if result.returncode != 0:
error = result.stderr.decode("utf-8", "replace").strip()
raise RuntimeError("wkhtmltopdf failed ({}): {}".format(result.returncode, error))
output = Path(destination)
if not output.is_file() or output.stat().st_size == 0:
raise RuntimeError("wkhtmltopdf reported success but produced no PDF")
return outputFor untrusted HTML, write sanitized content to a controlled temporary file and use a dedicated low-privilege worker. The wkhtmltopdf project 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 this as a server-security boundary, not merely a formatting concern.
Free tools Windows power users keep installed
One-click scans. No signup required.
Useful runtime options and their trade-offs
--enable-local-file-accessmay be required for local CSS or images, but it expands what a document can read. Enable it only for trusted, controlled files.--javascript-delaygives client-side rendering time, while increasing latency. Prefer a deterministic page-ready condition in your application when possible.--no-imagesreduces work but changes output; use it only when images are unnecessary.- Set an application timeout and terminate stuck processes. Do not let a request create unlimited concurrent renderers.
- Use absolute asset URLs or a controlled base URL, and ensure DNS, CA certificates and outbound access exist in the container.
Troubleshooting
“not found” or the binary will not start
Check command -v, executable permissions and ldd. On Alpine, a glibc-oriented binary commonly fails because the required libc is absent. Replace it with an Alpine build for the correct architecture rather than adding random compatibility libraries.
Package cannot be selected
Your branch, repository selection or architecture may not provide it. Inspect /etc/apk/repositories and apk policy wkhtmltopdf. Do not install a package from an unrelated branch merely because its version number looks close.
Blank pages, missing fonts or squares
Inspect fontconfig/freetype linkage and installed fonts, then rerun the fixture in the final image. Confirm that remote font and image requests are reachable and that the selected Qt build supports the required rendering behavior.
Conversion hangs or exits nonzero
Capture stderr, enforce a timeout and test the URL from inside the container. Common causes include blocked network access, JavaScript that never settles, TLS/CA problems, authentication, malformed HTML or resource loops.
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 minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutput differs from another environment
Compare Alpine branch, architecture, wkhtmltopdf version, Qt patch level, fonts, locale, timezone and network responses. “It starts” is not a reproducibility guarantee.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your actual goal is a clean website image or PDF rather than maintaining a wkhtmltopdf container, ScreenshotNeo provides a website screenshot API and MCP server. One request handles the capture:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for options and response details. It removes cookie/consent banners, newsletter popups and chat widgets before capture; bot checks, blank pages and failed loads are not billed, and response headers identify the page verdict and billing status. Its MCP server includes take_screenshot, get_page_info and capture_pdf for AI agents. 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.
Cost, reliability and maintenance decisions
A repository package is usually the simplest operational path, but only when its branch and architecture match and its Qt behavior meets your needs. A custom build gives control over Qt and dependencies but creates an ongoing rebuild and security-update obligation. Pin the base image, package repository snapshot or build inputs, executable checksum and fonts; then rerun the fixture after every upgrade. Keep rendering asynchronous when PDFs are large, cap concurrency and record stderr and exit codes for diagnosis.
Frequently Asked Questions
Does Python 3.6 install wkhtmltopdf automatically?
No. wkhtmltopdf is an OS executable; install and validate it in the Alpine image, then invoke it from Python.
Can I use the official generic Linux download on Alpine?
Do not assume so. Alpine uses musl libc, and the project documents failures with generic binaries. Select an Alpine-built artifact or build for your target.
Is the historical Alpine v3.9 Python 3.6 package archive a current solution?
No. It is historical branch evidence only and does not establish a supported present-day combination or architecture-independent recipe.
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.
