Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Start by viewing the exact HTML Django renders, then inspect the wkhtmltopdf command and error output that pdfkit uses to turn it into a PDF. If the rendered HTML is blank, fix the Django view, template, or context. If it contains the expected content, check the converter binary, asset access, JavaScript timing, encoding, and response handling. A blank PDF alone does not identify which stage failed.
First locate the failure: Django HTML or PDF conversion?
pdfkit is a Python wrapper around the separate wkhtmltopdf executable. That means a PDF can be blank because Django rendered empty HTML, because the renderer could not load content or assets, or because the generated PDF response was handled incorrectly. Diagnose those stages separately instead of changing several settings at once.
Inspect the HTML Django actually rendered
Use the same view, template, and context as the PDF endpoint. The django-pdfkit documentation describes an ?html query option for returning HTML during debugging. For example, if your PDF view is at /reports/weekly.pdf, try its documented HTML debug mode, such as /reports/weekly.pdf?html, in a development environment. Confirm that the response source contains the expected text and elements; do not rely only on what a browser displays after JavaScript runs.
PC 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 & 11Crashes, 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 minuteIf the HTML itself is empty or incomplete, inspect the template selected by the view, the context passed to it, conditional template branches, and the data lookup that feeds those variables. Fix that output first. wkhtmltopdf cannot render content that Django did not put in the HTML.
#1 Best Overall
If HTML looks right, move to converter diagnostics
Save or otherwise inspect the rendered HTML and compare it with the PDF output. Then capture pdfkit’s generated command, exit status, and stderr from the same environment that runs Django. pdfkit’s project troubleshooting guidance recommends running the command shown in an error directly to expose the underlying wkhtmltopdf failure. By default, pdfkit uses quiet mode, so diagnostics may be hidden unless you enable them.
Do not assume a particular root cause until you have both the rendered HTML and converter output. A browser-rendered page and a server-side PDF render can differ in resource access, JavaScript execution, and runtime environment.
Check that Django can find the right wkhtmltopdf executable
Install wkhtmltopdf in the environment used by the Django process, not just on a developer workstation. A command that works in an interactive shell may not be visible to a web worker running with a different PATH, user, container, or service configuration.
Use the setting for the integration you installed
The package-specific setting names are not interchangeable:
Rank #2
django-wkhtmltopdfdocumentsWKHTMLTOPDF_CMDfor the executable path.django-pdfkitdocumentsWKHTMLTOPDF_BIN.
Check which Django integration your project actually uses, then follow that package’s documentation and verify the path from the running process. For example, a configuration for one package will not fix binary discovery if the project uses the other. The django-wkhtmltopdf documentation labels its package material version 3.2.0; django-pdfkit’s documentation labels its usage material version 0.3.1. Confirm the installed version and consult the corresponding documentation because labels and options can vary by release.
Run the failing command in the same environment
When pdfkit reports a command, reproduce that command as the Django service user or in the same container. Record stderr and the exit status. This helps distinguish a missing executable, an unsupported option, a resource-loading problem, and an application response issue. Avoid suppressing stderr while diagnosing; restore quieter production logging only after you can see actionable errors.
Verify CSS, images, fonts, and local-file permissions
Assets that load in your browser may not load in wkhtmltopdf. A browser might be using a logged-in session, a locally cached stylesheet, or a path unavailable to the server process. Check every stylesheet, image, font, and other resource from the renderer’s point of view, and check whether it is reachable with the same network and filesystem permissions.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
For remote assets
- Confirm URLs in the rendered HTML are absolute and reachable from the machine or container running wkhtmltopdf.
- Check whether authentication, firewall rules, DNS, TLS, or redirects prevent the converter from loading a resource.
- Look at converter diagnostics for load failures rather than inferring success from a browser on your own computer.
For Django static files and local paths
When using the documented static-file workflow in django-wkhtmltopdf, its documentation calls out Django’s STATIC_ROOT and collected static files. Ensure the files exist where the configured application expects them. Also note that wkhtmltopdf’s documented command-line options disable local-file access by default. If the HTML refers to local files, use the appropriate explicit access or allow options for your deployed binary, and limit what paths it can read.
Do not broadly enable local-file access for arbitrary or untrusted HTML. Local asset access can expose files available to the process; apply the narrowest access needed for trusted input.
Wait for JavaScript only when your page depends on it
Server-side PDF rendering does not necessarily behave like opening a page in a fully interactive browser. If JavaScript inserts the text, charts, or images that are missing, confirm that scripts are enabled and that the renderer waits long enough for the required work to finish. wkhtmltopdf documents options to enable or disable JavaScript and to delay capture.
Use a wait or delay based on the page’s actual behavior, not as a blind fix. If the expected content is already in the Django-rendered HTML, extra JavaScript delay is unlikely to solve an HTML-generation problem. Conversely, if the page depends on scripts, inspect whether those scripts load and complete before the PDF is produced.
Recommended Free Tools
Check encoding and the Django PDF response
Declare UTF-8 for Unicode content
If characters disappear, render incorrectly, or seem to affect surrounding output, check the document’s encoding metadata. django-wkhtmltopdf recommends declaring UTF-8 content-type metadata in the template. For example, include this in the HTML head:
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">Verify the actual rendered document contains the declaration and that the source content is encoded consistently.
Confirm the endpoint returns the generated PDF
Once the HTML and converter output look correct, inspect the Django response path: confirm the view returns the generated PDF bytes rather than an empty response, that exceptions are not being caught and replaced with an empty body, and that the response is served with a PDF content type. Compare the bytes or file produced by a direct converter run with the bytes returned by the endpoint. A valid PDF with no visible page content points back toward HTML, rendering, or asset problems; an empty or error response points toward conversion or response handling.
Use a safe diagnostic sequence
- Open the same Django endpoint in HTML debug mode if your integration supports it, or render the template through the normal view.
- Check the returned HTML source for the content expected on the PDF page.
- If HTML is wrong, fix template selection, context data, conditionals, and view logic before changing wkhtmltopdf settings.
- If HTML is right, verify the configured executable path and run the emitted conversion command in the Django runtime environment.
- Read stderr and check resource URLs, static-file paths, and local-file permissions.
- Investigate JavaScript timing only for content generated or changed by scripts.
- Check UTF-8 metadata when Unicode characters are missing, then compare converter output with the Django response.
Common blank-PDF symptoms and fixes
| Symptom | Likely stage to inspect | What to check |
|---|---|---|
| The HTML debug response is blank too | Django rendering | Template, context values, conditional branches, and view logic. |
| HTML contains content but PDF does not | wkhtmltopdf conversion | Executable path, stderr, unsupported options, resource loading, and script timing. |
| Text appears but styling, images, or fonts do not | Asset access | Absolute URLs, server reachability, collected static files, and local-file access settings. |
| Script-created content is missing | JavaScript execution or timing | Whether scripts are enabled, resources load, and capture waits for the required work. |
| Some non-ASCII characters disappear | Encoding | UTF-8 metadata and consistent source encoding. |
| Direct conversion works but the HTTP response is empty | Django response handling | Returned bytes, exception handling, and response content type. |
Security when converting HTML you do not fully control
The wkhtmltopdf project’s AppArmor security guidance says, “Wkhtmltopdf is not recommended for use when rendering HTML you don’t explicitly trust”. Treat user-supplied HTML and any content that can alter resource URLs as untrusted. In particular, do not grant broad filesystem access merely to make local assets load; use restrictive access controls and allow only the resources required for the conversion.
Or skip the browser setup: capture a visual screenshot
If your immediate need is to inspect how a URL renders in a browser, rather than produce a downloadable PDF, ScreenshotNeo is a website screenshot API and MCP server. It does not replace pdfkit for creating a PDF from a Django template, but it can return a screenshot of a URL for visual debugging. Its API accepts a URL and returns an image or PDF; for a screenshot, a one-call cURL example is:
Best Value
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 setup. Before capture, it accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each of those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. An MCP server exposes take_screenshot, get_page_info, and capture_pdf 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 screenshots. Every feature is available on every plan.
Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Does pdfkit render the Django template itself?
No. Django produces the HTML, and pdfkit passes it to the separate wkhtmltopdf executable for conversion.
Free tools Windows power users keep installed
One-click scans. No signup required.
Which Django setting changes the wkhtmltopdf binary path?
It depends on the integration: django-wkhtmltopdf documents WKHTMLTOPDF_CMD, while django-pdfkit documents WKHTMLTOPDF_BIN.
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.
