Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →HostNotFoundError means the wkhtmltopdf process launched by Python PDFKit could not resolve or reach the hostname in the URL it was asked to render. Start by exposing the renderer’s output, then run the same wkhtmltopdf command directly inside the application’s actual runtime. This separates a bad URL, container-specific DNS, local-server reachability, security confinement, and an incompatible binary from a PDFKit configuration problem.
What the error means
Python PDFKit is a wrapper, not the HTML renderer. It starts the separate wkhtmltopdf executable, which loads the supplied URL or HTML and writes the PDF. A message such as wkhtmltopdf http://google.com google.pdf followed by HostNotFoundError therefore identifies a failure while the renderer was loading a hostname.
The first question is not “is the Python package installed?” but “can this exact renderer, in this exact runtime, resolve and connect to that host?” A missing executable usually raises a different error, although an incorrect executable path can prevent useful testing.
Fastest diagnostic path
- Turn on verbose output. PDFKit normally hides most wkhtmltopdf output. Add
verbose=Trueand preserve the complete stderr/stdout in your application log. - Record the exact input. Check the scheme, hostname, port, path, spelling, and URL encoding. Test a fully qualified URL such as
https://example.com/, not a browser-only shorthand. - Run wkhtmltopdf directly. Use the same executable, URL, options, container or host, service account, environment variables, and network namespace as the Python process.
- Classify the result. If the direct command fails with the same host error, investigate DNS, routing, policy, or the target server. If it succeeds, compare PDFKit’s generated command and options with the working command.
Enable PDFKit diagnostics
import pdfkit
url = "https://example.com/"
config = pdfkit.configuration(wkhtmltopdf="/usr/local/bin/wkhtmltopdf")
try:
pdfkit.from_url(url, "out.pdf", configuration=config, verbose=True)
except Exception as exc:
print(f"PDF generation failed: {exc}")
raiseUse the executable path that exists in your deployment. Do not change the path merely because a hostname failed; path discovery and hostname resolution are separate failure classes.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
Reproduce outside Python
/usr/local/bin/wkhtmltopdf --log-level info "https://example.com/" out.pdfRun this from the same container, virtual machine, user account, and service unit as the application. A URL that works in your desktop browser may fail in a container with different DNS, proxy settings, firewall rules, or certificates.
Fix the URL and hostname branch
Validate DNS from the renderer’s environment
Inspect the runtime’s resolver configuration and test the hostname with the operating-system tools available in that image. For example:
getent hosts example.com
cat /etc/resolv.conf
curl -v --location "https://example.com/"These commands are supporting checks; the decisive test remains the direct wkhtmltopdf invocation. If name lookup fails there too, correct the container or host DNS configuration, network attachment, proxy setup, or hostname. Do not “fix” the problem by hard-coding an IP unless you control the endpoint and understand the consequences of TLS certificate validation, virtual hosting, and changing addresses.
Check ports, schemes, and redirects
A resolvable host can still be unreachable on its port. Confirm that the runtime can reach the URL’s HTTP or HTTPS endpoint and follow any redirect chain. Internal services may require a proxy, an authorization header, or a network route unavailable to the PDF worker.
When the URL is localhost
localhost means the machine or network namespace where wkhtmltopdf runs. In a container, it normally means that container—not your laptop and not necessarily the web container that serves your application.
- Confirm the application server is running and listening on the expected port.
- Check whether it listens only on
127.0.0.1when the renderer is in another container. Use a reachable service name or network address instead. - Verify the renderer’s container can resolve and connect to that address.
- Make sure the URL includes the correct scheme and port, for example
http://web:8000/invoice/42.
An archived PDFKit issue documents a HostNotFoundError involving a localhost URL; it is useful as a historical example, not proof that every localhost failure has one universal fix: the issue report.
Check security confinement and network policy
AppArmor, SELinux, seccomp, egress firewalls, and service-level sandboxing can allow the Python process to start while denying the renderer’s network operations. Review audit logs and the policy attached to the wkhtmltopdf executable or service.
The official wkhtmltopdf AppArmor guide shows a profile using the nameservice abstraction. Without appropriate name-service permissions, DNS and related network attempts can be denied. Adapt the profile narrowly to the URLs the application is intended to access; do not disable confinement globally as a first response.
Verify the wkhtmltopdf build and platform
Run:
wkhtmltopdf --version
uname -a
cat /etc/os-releaseThe wkhtmltopdf downloads page identifies the 0.12.6 series as a stable series released June 11, 2020: official downloads. That page’s release information is not a guarantee that it is the newest build for your deployment. Install a binary appropriate for your operating system and CPU architecture, and test it in the image that will run production.
The project specifically cautions that generic Linux binaries may fail across distributions, including the difference between Alpine’s musl libc and glibc environments: platform guidance. Prefer a distribution-compatible package or image. A binary mismatch can produce crashes or unrelated rendering failures, so confirm the direct URL test before attributing every error to DNS.
PDFKit configuration that helps—and what it cannot do
Set an explicit executable path
config = pdfkit.configuration(wkhtmltopdf="/usr/bin/wkhtmltopdf")
pdfkit.from_url("https://example.com/", "out.pdf", configuration=config, verbose=True)Use this when PDFKit cannot find the executable or is selecting the wrong one. It does not repair a hostname that the selected renderer cannot resolve.
Do not hide the underlying failure
Options such as --load-error-handling ignore can let a job continue after a page-load error. They may produce an incomplete PDF while masking the missing page. The archived issue evidence shows that ignore/skip handling does not restore name resolution or make unavailable content appear: historical report. Use such options only when omission is explicitly acceptable and validate the resulting document.
Recommended Free Tools
Pass the same headers, cookies, or proxy settings
If the target is private, reproduce the production request conditions. PDFKit can pass wkhtmltopdf options for headers and cookies, but authentication does not help if DNS or routing fails first. Keep credentials out of logs and generated command lines where possible.
Common symptoms and fixes
| Symptom | Likely branch | Action |
|---|---|---|
| Direct wkhtmltopdf also reports HostNotFoundError | DNS, routing, hostname, policy, or local-server reachability | Test from the same runtime; inspect resolver, network, and confinement logs. |
| Browser works, renderer fails | Different network namespace, proxy, certificates, or user policy | Run diagnostics inside the worker/container, not on the desktop. |
| Only localhost fails | Loopback points to the renderer’s own environment | Use a reachable service address and verify listening interfaces and ports. |
| Executable not found | Installation or path discovery | Install a compatible build and set pdfkit.configuration(wkhtmltopdf=...). |
| Fails only on Alpine or a new base image | libc or binary compatibility | Use a build matched to the distribution and architecture. |
| PDF is created but content is missing | Ignored load error, blocked resources, or premature capture | Remove ignore handling, review verbose output, and verify resource access. |
A repeatable production checklist
- Log the exact URL without exposing secrets.
- Log the wkhtmltopdf version and configured path.
- Capture verbose renderer output and exit status.
- Run the direct command in the same image and identity.
- Test DNS, TCP reachability, redirects, and required proxy or credentials.
- Check AppArmor/SELinux and egress policy.
- Confirm the binary matches the distribution and architecture.
- Remove temporary diagnostics or redact sensitive headers before retaining logs.
- After a fix, test an external URL, an internal URL, and the real production URL.
Or skip the browser setup
If your real requirement is a reliable website image or PDF rather than maintaining a wkhtmltopdf runtime, ScreenshotNeo provides a website screenshot API and MCP server. It accepts a URL in one request and can return PNG, JPEG, WebP, or PDF. Before capture it accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled.
Only clean shots are billed. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
Use the documented API parameters and options for full-page or element capture, device and viewport settings, dark mode, retina scale, PDF paper and page ranges, custom CSS/JavaScript, clicks, waits, blocking rules, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting, and OpenAPI integration. See the ScreenshotNeo documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);There is a free allowance of 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is on every plan. Create a free ScreenshotNeo account.
FAQ
Is HostNotFoundError a Python import problem?
Usually no. It is reported during the external wkhtmltopdf process’s attempt to load the requested host.
Should I retry the PDF job?
Retries help only with transient network failures. First make the direct renderer command succeed; otherwise retries repeat the same deterministic DNS or policy failure.
Can an IP address permanently solve it?
Not safely in every case. HTTPS certificates, virtual hosts, load-balancer changes, and rotating addresses can make an IP substitution incorrect.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsFrequently Asked Questions
Is HostNotFoundError a Python import problem?
Usually no. It is reported during the external wkhtmltopdf process’s attempt to load the requested host.
Should I retry the PDF job?
Retries help only with transient network failures. First make the direct renderer command succeed; otherwise retries repeat the same deterministic DNS or policy failure.
Can an IP address permanently solve it?
Not safely in every case. HTTPS certificates, virtual hosts, load-balancer changes, and rotating addresses can make an IP substitution incorrect.
The Bottom Line
Expose verbose output, reproduce the exact command directly in the renderer’s runtime, and fix the branch that fails there: hostname/server reachability, container DNS, security policy, or binary compatibility.
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.
