Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →That 10% pause is a loading-progress symptom, not a diagnosis. It can come from failed local or remote resources, JavaScript that never becomes ready, PHP pipe handling, an unavailable X display, permissions, or differences between wkhtmltopdf builds. Reproduce the exact command outside PHP, reduce the input to a tiny local file, then add dependencies back one at a time. This isolates the cause without guessing.
What the 10% marker actually tells you
wkhtmltopdf reports progress while it loads and renders a page. A process that remains at 10% is therefore stuck somewhere in loading or execution; the number does not identify JavaScript as the cause. One reported failure persisted with local HTML and with --disable-javascript, while another worked from a shell but failed from PHP because file:// assets could not be loaded.
Use the percentage as a boundary for investigation, not as a fix. First determine whether the same input and binary fail for the same operating-system user outside PHP.
Start with a reproducible environment record
Capture the variables that change renderer behavior
- Output of
wkhtmltopdf --version, including whether the package is a patched-Qt or unpatched build. - Operating-system and distribution version, PHP version, and the account that executes the worker.
- The absolute wkhtmltopdf path, current working directory,
PATH, locale, proxy settings, and other relevant environment variables. - The exact URL or HTML file, command-line arguments, cookies or authorization headers, and the destination path.
The project’s support guidance asks for the wkhtmltopdf version, OS version, and a detailed reproducible HTML/CSS/JS case. Keep that information while troubleshooting; changing several variables at once makes the result ambiguous.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
![PDF Extra 2024| Complete PDF Reader and Editor | Create, Edit, Convert, Combine, Comment, Fill & Sign PDFs | Lifetime License | 1 Windows PC | 1 User [PC Online code]](https://m.media-amazon.com/images/I/41eZq4aiipL._SL160_.jpg)
- EDIT text, images & designs in PDF documents. ORGANIZE PDFs. Convert PDFs to Word, Excel & ePub.
- READ and Comment PDFs – Intuitive reading modes & document commenting and mark up.
- CREATE, COMBINE, SCAN and COMPRESS PDFs
- FILL forms & Digitally Sign PDFs. PROTECT and Encrypt PDFs
- LIFETIME License for 1 Windows PC or Laptop. 5GB MobiDrive Cloud Storage Included.
Run the exact job outside PHP
Compare command, user, and files character for character
- Run the command from a shell as the same OS user used by PHP, if possible. Use the same absolute binary path, working directory, input, output path, and options.
- Redirect standard error to a log, but do not discard it. Resource and JavaScript warnings often explain an apparent 10% freeze.
- Check the exit status and confirm that the produced PDF is complete and readable.
- Run the same command from PHP. Compare the complete command strings and the environment, not just the URL.
If the shell succeeds but PHP fails, prioritize process plumbing, permissions, environment variables, and PHP’s access to local files or the network. If both fail, reduce the document before investigating PHP.
Reduce the document to a minimal loading test
Add one dependency at a time
- Create a local HTML file containing only plain text and an explicit character encoding.
- Render that file with the same binary and user.
- Add the stylesheet, images, web fonts, JavaScript, redirects, authentication, iframes, and remote API calls one layer at a time.
- When the hang returns, inspect that layer’s URL, permissions, response, and timing.
A failure that remains with plain local HTML points toward the binary, display, permissions, or process boundary rather than your application page. A failure introduced by an asset or script is a loading or readiness problem.
Use PHP process pipes safely
Why wrappers commonly appear to hang
With proc_open, PHP can block if the child’s stderr or stdout pipe fills while the parent waits for the process. Progress messages must stay on stderr; PDF bytes must stay on stdout or a file. Close stdin after the complete document has been written, continuously drain both output streams, and record the exit code.
Rank #2
- Edit PDFs with Ease. Modify text, images, and layouts directly within your PDF documents.
- Convert & Organize. Export PDFs to Word, Excel, or ePub, and organize files with ease.
- Read & Annotate. Enjoy intuitive reading modes and powerful tools to comment, highlight, and mark up PDFs.
- Create & Manage PDFs. Create new PDFs, combine multiple files, scan documents, and compress for easy sharing.
- Fill & Sign Forms. Complete forms and digitally sign documents with secure e-signature tools.
Runnable PHP example
<?php
$binary = '/usr/local/bin/wkhtmltopdf';
$workingDir = '/var/tmp';
$html = '<!doctype html><html><head><meta charset="utf-8"></head><body>Hello</body></html>';
$outputPath = __DIR__ . '/result.pdf';
$command = escapeshellarg($binary) . ' --disable-smart-shrinking - -';
$spec = [
0 => ['pipe', 'r'],
1 => ['pipe', 'w'],
2 => ['pipe', 'w'],
];
$env = ['PATH' => '/usr/local/bin:/usr/bin:/bin'];
$proc = proc_open($command, $spec, $pipes, $workingDir, $env);
if (!is_resource($proc)) {
throw new RuntimeException('Could not start wkhtmltopdf');
}
fwrite($pipes[0], $html);
fclose($pipes[0]);
stream_set_blocking($pipes[1], false);
stream_set_blocking($pipes[2], false);
$pdf = '';
$stderr = '';
while (true) {
$read = [];
if (!feof($pipes[1])) $read[] = $pipes[1];
if (!feof($pipes[2])) $read[] = $pipes[2];
if (!$read) break;
$write = null;
$except = null;
if (stream_select($read, $write, $except, 1) === false) break;
foreach ($read as $stream) {
$chunk = stream_get_contents($stream);
if ($stream === $pipes[1]) $pdf .= $chunk;
else $stderr .= $chunk;
}
}
fclose($pipes[1]);
fclose($pipes[2]);
$exitCode = proc_close($proc);
file_put_contents($outputPath, $pdf);
if ($exitCode !== 0 || strlen($pdf) === 0) {
throw new RuntimeException("wkhtmltopdf failed ($exitCode): $stderr");
}
echo "Wrote $outputPathn";
?>For production, add a wall-clock timeout around the loop and terminate the child when it exceeds your limit. Use an explicit working directory and absolute binary path; web-server workers often have a different PATH and home directory than an interactive shell.
Separate JavaScript readiness from ordinary loading
Isolation tests
- Run once with
--disable-javascript. If it completes, JavaScript or a script-dependent resource is implicated; this test is not a permanent fix for pages that require scripts. - Enable
--debug-javascriptwhile diagnosing so script errors are visible. - Try
--stop-slow-scriptsto expose a runaway script. - For a page that needs JavaScript, use a bounded
--javascript-delayor have the page set a deterministic value consumed with--window-status. The documented default JavaScript delay is 200 milliseconds, which may be too short for a real application and should not be replaced with an unbounded wait.
Prefer a page-controlled readiness signal over an arbitrary long delay. Keep every wait finite so a failed API or script cannot hold a PHP worker indefinitely.
Investigate failed resources and authentication
Read the warnings instead of hiding them
Look for errors involving images, CSS, fonts, redirects, iframes, HTTPS, and file:// URLs. Under the PHP account, verify DNS resolution, outbound HTTPS access, read permission on every local asset, and the cookies or authorization required by protected pages.
Rank #3
- Create and edit PDFs. Collaborate with ease. E-sign documents and collect signatures. Get everything done in one app, wherever you go.
- Edit text and images without jumping to another app.
- E-sign documents or request e-signatures on any device. Recipients don’t need to log in to e-sign.
- Convert PDFs to editable Microsoft Word, Excel, or PowerPoint documents.
- Share PDFs for collaboration. Commenting features make it easy for reviewers to comment, mark up, and annotate.
--load-error-handling skip or ignore can classify whether one failed resource is blocking completion. Treat those switches as diagnostic tools first: they can produce a PDF with missing content. Before shipping, choose an explicit policy for incomplete assets and validate the resulting document.
Check Linux display requirements
When X11 is the missing dependency
Some binaries or distribution packages expect an X11 display even for headless work. Run a controlled test with xvfb-run, or configure a persistent virtual display for the worker. The PHP wrapper documentation describes this workaround and notes its additional CPU and session overhead.
Windows 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 reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchIf the virtual-display test succeeds, decide whether to operate that display continuously or switch to a known static wkhtmltopdf build. Document the package’s patched-Qt and font behavior; different builds can change SSL handling, font rendering, JavaScript, and display assumptions.
Rank #4
- Perfect Adobe Acrobat Pro alternative – lifetime license for Windows 10 and 11.
- EDIT text, images, pages, hyperlinks, designs in PDF documents. ORGANIZE PDFs.
- READ and Comment on PDFs – Intuitive reading modes & document commenting and mark up tools!
- CREATE, COMBINE, SCAN and COMPRESS PDFs.
- FILL forms & Digitally Sign PDFs. Work with Digital certificates
Confirm the version and package provenance
The project’s official downloads page lists stable series 0.12.6, released June 11, 2020. That date does not mean every operating-system package is identical: distributions may backport patches or ship an unpatched build. Record the exact package and build string when comparing machines, and do not assume that moving the same command between packages preserves behavior.
Choose the fix based on the actual constraint
| Observed constraint | Most useful next action | Trade-off |
|---|---|---|
| JavaScript is unnecessary | Test with --disable-javascript |
Pages that require scripts will be incomplete. |
| JavaScript is required | Use bounded delay or deterministic --window-status; inspect debug output |
Readiness logic must be maintained with the page. |
| Remote assets or login are required | Fix DNS, HTTPS, cookies, headers, and file permissions; verify as the PHP user | Network and credential failures remain possible at render time. |
| No X display is available | Test xvfb-run or a persistent virtual display |
Consumes extra CPU and session resources. |
| Missing assets are acceptable only temporarily | Use --load-error-handling options to classify the fault, then enforce a deliberate policy |
Ignoring errors can silently create incomplete PDFs. |
| Behavior differs across hosts | Compare exact binary builds, patched-Qt status, fonts, OS, and environment | Standardizing builds adds deployment work but improves reproducibility. |
Treat HTML rendering as a security boundary
The 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 running on!” Sanitize user HTML and JavaScript, run the renderer with least privilege, isolate the worker, restrict network egress where practical, and avoid exposing internal files or metadata to rendered content.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.When to escalate with a minimal case
Open an issue or ask for operational help only after you can provide the exact command, binary version, OS, PHP invocation, minimal HTML/CSS/JS, stderr, exit code, and whether the same case reproduces outside PHP. State whether JavaScript, remote assets, authentication, and an X display are required. This lets someone distinguish a renderer defect from a PHP boundary problem.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Best Value
- ALL-IN-ONE SOLUTION – read, edit, convert, merge and protect your PDF files
- MAXIMUM FUNCIONALITY – create interactive forms, compare PDFs, bates numbering, find and replace text or colors, convert documents, OCR engine, comment, highlight, fill out and print forms, document protection and others
- EASY TO INSTALL AND USE – well-structured user-interface, in-program instructions, free tech support whenever you need it
- GREAT VALUE FOR MONEY - why spend a fortune if you can have maximum functionality at a reasonable price - this also fits the requirements of companies very well
Or skip the browser setup
If your goal is a clean screenshot or PDF of a URL rather than repairing a wkhtmltopdf worker, ScreenshotNeo provides a single HTTP request. It is a separate rendering service, not a fix for a broken local wkhtmltopdf installation.
Before capture, ScreenshotNeo accepts cookie/consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import 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)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo API documentation for the 63 capture options, including full-page lazy-image loading, CSS-element capture, device and retina settings, PDF paper and page controls, custom CSS/JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen-TTL caching, signed links, async webhooks, bulk capture, usage, and the OpenAPI specification. The parameter names used by other screenshot APIs also work, easing migration.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and yearly billing gives two months free. Sign up for the free ScreenshotNeo plan.
Troubleshooting checklist
| Symptom | Likely boundary | Check or fix |
|---|---|---|
| Shell succeeds; PHP remains at 10% | Different user, PATH, directory, permissions, or blocked pipes | Use absolute paths, explicit working directory, same user, continuous stream draining, and logged exit code. |
| Plain local HTML also hangs | Binary, display, permissions, or process plumbing | Test the exact minimal file, compare builds, and run under xvfb-run if appropriate. |
| Disabling JavaScript makes it finish | Script error or indefinite readiness wait | Inspect --debug-javascript, try --stop-slow-scripts, and implement bounded readiness. |
Warnings mention file:// or fonts |
PHP account cannot read local resources | Use readable absolute paths and verify access as the execution user. |
| PDF finishes but content is missing | Ignored resource errors or premature readiness | Remove permissive load-error handling and validate all required assets. |
| Only one host fails | Package, fonts, SSL, X11, or environment difference | Compare version/build, OS, fonts, display, environment, and network policy. |
Frequently Asked Questions
Is a 10% hang proof that JavaScript is broken?
No. It is a loading-progress symptom. JavaScript is only one hypothesis; local assets, PHP pipes, permissions, display setup, and binary differences can produce the same marker.
Should I permanently use –load-error-handling ignore?
Only if incomplete documents are an explicitly accepted outcome. Use it first to classify a resource failure, then choose and validate a deliberate production policy.
Do I always need xvfb on Linux?
No. It depends on the binary or package’s X11 expectations. A controlled xvfb-run test shows whether a missing display is involved; it also adds CPU and session overhead.
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.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
