Recommended Free Tools
Wicked PDF hangs because its Rails wrapper is waiting for an external wkhtmltopdf process to finish. Diagnose that process first: identify the executable and version, verify that its CPU architecture matches your Mac, remove conflicting provider gems, reproduce the conversion outside Rails, and then check blocking options such as --window-status and local-file access. Once the standalone command completes reliably, point Wicked PDF at that exact executable and reproduce the same arguments.
What a “hang” means in Wicked PDF
Wicked PDF does not render a document inside Ruby. It starts the wkhtmltopdf executable, passes it HTML and options, and waits for the child process to return. A request that appears frozen can therefore be caused by the binary, its architecture, JavaScript that never finishes, inaccessible assets, an option that intentionally waits, or the macOS runtime itself.
Separate the problem into two tests:
- Standalone test: can the selected
wkhtmltopdfbinary convert a tiny HTML file from Terminal? - Rails test: does Wicked PDF invoke that same binary with arguments that also work in the standalone test?
If the standalone command hangs, changing a controller, view, or Rails timeout will not repair the renderer. If it succeeds, compare the command Wicked PDF generated with your working command; the difference normally exposes the cause.
1. Record the environment before changing anything
Run these commands from the same shell and, where applicable, the same deployment user that runs Rails:
#1 Best Overall
- SUPERCHARGED BY M5 — The 14-inch MacBook Pro with M5 brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. Featuring all-day battery life and a breathtaking Liquid Retina XDR display with up to 1600 nits peak brightness, it’s pro in every way.*
- HAPPILY EVER FASTER — Along with its faster CPU and unified memory, M5 features a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance. So you can blaze through demanding workloads at mind-bending speeds.
- BUILT FOR APPLE INTELLIGENCE — Apple Intelligence is the personal intelligence system that helps you write, express yourself, and get things done effortlessly. With groundbreaking privacy protections, it gives you peace of mind that no one else can access your data — not even Apple.*
- ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.
- APPS FLY WITH APPLE SILICON — All your favorites, including Microsoft 365 and Adobe Creative Cloud, run lightning fast in macOS.*
which wkhtmltopdf
wkhtmltopdf --version
ruby -v
bundle exec ruby -e 'puts Gem.loaded_specs["wicked_pdf"]&.version'
bundle list | grep -E 'wicked_pdf|wkhtmltopdf-binary'
uname -m
sw_versSave the complete output. The architecture reported by uname -m is usually arm64 on Apple Silicon or x86_64 on an Intel Mac. Also record the macOS release, Wicked PDF version, and every wkhtmltopdf provider gem. When asking for help, include a minimal HTML/CSS/JavaScript reproduction and the exact command line, not only a Rails stack trace.
2. Make sure one compatible wkhtmltopdf is installed
Check the path and version
which wkhtmltopdf can point to a system installation, a Homebrew location, or a binary supplied by a Bundler gem. Confirm that the file at that path is the version you expect:
type -a wkhtmltopdf
ls -l "$(which wkhtmltopdf)"
file "$(which wkhtmltopdf)"
"$(which wkhtmltopdf)" --versionThe official downloads page lists a 64-bit macOS installer and identifies 0.12.6 as the stable series released June 11, 2020. Treat that as a historical release fact, not proof that a downloaded binary is current or Apple-Silicon native; verify the binary you deploy.
Handle Intel binaries on Apple Silicon
An Intel-only executable may fail immediately on an Apple-Silicon Mac with Bad CPU type in executable. A process that is silently launched through an incompatible wrapper can also look like a timeout. Use file to see whether the executable contains an arm64 slice, an x86_64 slice, or both. If it is Intel-only, install a known-compatible build or deliberately run the entire Ruby process under the same Rosetta strategy; do not mix an arm64 Rails process with an unintentionally selected binary.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Remove duplicate provider gems
Having both wkhtmltopdf-binary and wkhtmltopdf-binary-edge installed can leave Bundler or PATH selecting an unexpected executable. Keep one provider, bundle again, and re-check which wkhtmltopdf and wkhtmltopdf --version. A clean bundle is easier to diagnose than multiple binaries with similar names.
Rank #2
- FAST RUNS IN THE FAMILY — The 16-inch MacBook Pro with the M5 Pro or M5 Max chip brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. With all-day battery life, double the starting storage,* and a breathtaking Liquid Retina XDR display, it’s pro in every way.*
- BUCKLE UP — Along with a next-generation CPU, faster unified memory, and up to 2x faster SSD storage,* M5 Pro and M5 Max feature a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance and on-device training capabilities. So you can blaze through demanding workloads at mind-bending speeds.
- BUILT FOR AI — Apple silicon, and every major component that powers it, is designed to run demanding on-device AI workloads like LLM inference and training. And Apple Intelligence helps you write, express yourself, and get things done effortlessly with groundbreaking privacy protections at every step.*
- ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.*
- MACOS RUNS APPS FAST — All your go-to apps run lightning fast in macOS, including built-in apps like FaceTime and Messages. Plus, built-in virus protection and free software updates help keep your Mac running smoothly and securely.
3. Point Wicked PDF at the intended executable
Do not rely on PATH when several shells, launch agents, or application servers may use different environments. Configure an absolute path in an initializer:
# config/initializers/wicked_pdf.rb
WickedPdf.configure do |config|
config.exe_path = "/absolute/path/to/wkhtmltopdf"
endReplace the example with the path printed by which wkhtmltopdf, or with the path your chosen provider exposes. Restart the Rails process after changing the initializer. If your deployment uses a release directory, use a stable path or update the setting during each release so it does not point at a deleted file.
4. Reproduce the conversion outside Rails
Create the smallest possible fixture. Start with no JavaScript, remote assets, or custom flags:
cat > /tmp/wkhtml-test.html <<'EOF'
<!doctype html>
<html><body><h1>wkhtmltopdf test</h1><p>Rendered locally.</p></body></html>
EOF
wkhtmltopdf /tmp/wkhtml-test.html /tmp/wkhtml-test.pdf
open /tmp/wkhtml-test.pdfDo not add --quiet while investigating. Preserve standard error and the exit status:
set -o pipefail
wkhtmltopdf /tmp/wkhtml-test.html /tmp/wkhtml-test.pdf 2>/tmp/wkhtmltopdf.stderr
echo "exit=$?"
cat /tmp/wkhtmltopdf.stderrIf this minimal conversion hangs, investigate the executable, architecture, macOS compatibility, fonts, and command-line options before touching your Rails view. If it finishes, progressively add the real HTML, stylesheets, images, and JavaScript until the hang returns. The last change identifies the useful branch of the investigation.
Rank #3
- FAST RUNS IN THE FAMILY — The 16-inch MacBook Pro with the M5 Pro or M5 Max chip brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. With all-day battery life, double the starting storage,* and a breathtaking Liquid Retina XDR display, it’s pro in every way.*
- BUCKLE UP — Along with a next-generation CPU, faster unified memory, and up to 2x faster SSD storage,* M5 Pro and M5 Max feature a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance and on-device training capabilities. So you can blaze through demanding workloads at mind-bending speeds.
- BUILT FOR AI — Apple silicon, and every major component that powers it, is designed to run demanding on-device AI workloads like LLM inference and training. And Apple Intelligence helps you write, express yourself, and get things done effortlessly with groundbreaking privacy protections at every step.*
- ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.*
- MACOS RUNS APPS FAST — All your go-to apps run lightning fast in macOS, including built-in apps like FaceTime and Messages. Plus, built-in virus protection and free software updates help keep your Mac running smoothly and securely.
5. Check options that deliberately wait
--window-status
With --window-status ready, wkhtmltopdf waits until the page sets window.status = "ready". If your application never sets that exact value, conversion can wait indefinitely. Temporarily remove the option. If you need it, set the status only after all required asynchronous work completes:
<script>
// Run after data and images required by the PDF are ready.
window.status = "ready";
</script>Test the page without the flag first, then add it back with the smallest possible fixture. A typo in the status string, a JavaScript exception, or a code path that never runs has the same symptom as a renderer failure.
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 reinstallJavaScript, delays, and network waits
Remove custom JavaScript, long delays, and network-idle-style waits while isolating the fault. A third-party script can keep the page busy, throw an exception, or wait on a request that is blocked in the server environment. Add scripts back one at a time and keep a finite timeout in the surrounding job so a genuinely broken page cannot consume a worker forever.
6. Verify CSS, images, fonts, and local-file access
Wicked PDF runs outside the browser session where you normally inspect the page. Relative URLs, authentication cookies, and development-only hostnames may therefore fail. Prefer absolute, reachable asset URLs or the asset helper tags documented by Wicked PDF. Confirm that the Rails process can resolve the hostname and that any required credentials are supplied to the renderer.
For intentionally local assets, use the appropriate local-file-access setting for your wkhtmltopdf build and make sure the process has filesystem permission to read the files. A missing image may not produce a clear Rails exception, yet a page that waits for an asset or script can prevent completion. Test with one inline style and one local image, then expand the fixture.
Rank #4
- SUPERCHARGED BY M5 — The 14-inch MacBook Pro with M5 brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. Featuring all-day battery life and a breathtaking Liquid Retina XDR display with up to 1600 nits peak brightness, it’s pro in every way.*
- HAPPILY EVER FASTER — Along with its faster CPU and unified memory, M5 features a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance. So you can blaze through demanding workloads at mind-bending speeds.
- BUILT FOR APPLE INTELLIGENCE — Apple Intelligence is the personal intelligence system that helps you write, express yourself, and get things done effortlessly. With groundbreaking privacy protections, it gives you peace of mind that no one else can access your data — not even Apple.*
- ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.
- APPS FLY WITH APPLE SILICON — All your favorites, including Microsoft 365 and Adobe Creative Cloud, run lightning fast in macOS.*
Also check fonts. A font lookup that works interactively may fail for a launch daemon or restricted service account. Replace custom fonts with a system font in the minimal test; if the hang disappears, fix the font path or package the font with the deployment.
Free tools Windows power users keep installed
One-click scans. No signup required.
7. Capture the command Wicked PDF actually runs
During diagnosis, preserve stderr and avoid quiet mode. Log (with secrets removed) the executable path, complete argument list, temporary HTML path, output path, and child-process exit status. Compare that command character-for-character with the standalone command that succeeds. Pay special attention to:
- an unexpected executable selected through PATH or Bundler;
--window-status, JavaScript delays, or other waiting flags;- relative asset URLs and local-file permissions;
- custom headers, cookies, or user-agent values that change server responses;
- an output path that the Rails user cannot create.
Use temporary files that remain available until the investigation ends. Deleting the input immediately after spawning the process can hide a race that looks like a renderer hang.
Common symptoms and fixes
| Symptom | Likely cause | Action |
|---|---|---|
Bad CPU type in executable |
Intel binary on Apple Silicon, or an incompatible wrapper | Install a compatible build, verify with file, and ensure Rails and the binary use a deliberate architecture strategy. |
| Command works in Terminal but not in Rails | Different PATH, user, permissions, working directory, or environment | Set config.exe_path to an absolute path and run the same command as the Rails service account. |
Removing --window-status fixes it |
The page never sets the requested status | Set the exact value after required JavaScript completes, or omit the option. |
| Blank or incomplete PDF, then a long wait | Blocked CSS, JavaScript, image, font, or local file | Use a minimal fixture, absolute/helper asset URLs, and verified local-file permissions. |
Two wkhtmltopdf versions appear in type -a |
Conflicting system and provider-gem installations | Remove the duplicate provider, choose one binary, and pin its absolute path. |
| No useful error because the request simply times out | Quiet mode or discarded stderr | Disable quiet mode, preserve stderr, and record the child exit status and arguments. |
Security and maintenance considerations
wkhtmltopdf’s project warns not to use it with untrusted HTML unless user-supplied HTML and JavaScript are sanitized; otherwise the renderer can enable a complete server takeover. Treat every URL, template, cookie, header, and local-file permission as part of your security boundary.
The wkhtmltopdf project is archived. That does not automatically make an existing, controlled workload unusable, but persistent macOS failures, modern CSS requirements, or difficult JavaScript pages are reasonable triggers to evaluate a maintained browser renderer. Compare candidates on CPU-architecture support, CSS and JavaScript fidelity, local-file behavior, timeout and logging controls, maintenance status, deployment complexity, and how much your existing Wicked PDF templates must change.
Best Value
- SUPERCHARGED BY M5 — The 14-inch MacBook Pro with M5 brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. Featuring all-day battery life and a breathtaking Liquid Retina XDR display with up to 1600 nits peak brightness, it’s pro in every way.*
- HAPPILY EVER FASTER — Along with its faster CPU and unified memory, M5 features a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance. So you can blaze through demanding workloads at mind-bending speeds.
- BUILT FOR APPLE INTELLIGENCE — Apple Intelligence is the personal intelligence system that helps you write, express yourself, and get things done effortlessly. With groundbreaking privacy protections, it gives you peace of mind that no one else can access your data — not even Apple.*
- ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.
- APPS FLY WITH APPLE SILICON — All your favorites, including Microsoft 365 and Adobe Creative Cloud, run lightning fast in macOS.*
Escalate with a reproducible case
Once you have reduced the failure, provide the macOS version, uname -m output, wkhtmltopdf version and path, Wicked PDF and provider-gem versions, exact command, stderr, and a small HTML/CSS/JavaScript fixture. This is the information the project’s support guidance requests, and it lets another engineer reproduce the wait without access to your application.
Or skip the browser setup
If your goal is simply to obtain a dependable screenshot or PDF rather than maintain a local wkhtmltopdf installation, ScreenshotNeo provides a website screenshot API and MCP server. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and whether it was billed. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
One GET request returns PNG, JPEG, WebP, or PDF. The API supports full-page captures with lazy images loaded, CSS-selector element capture, dark mode, device presets or custom viewports, retina scale, PDF paper size/margins/landscape/page ranges, custom CSS and JavaScript, pre-capture clicks, hidden selectors, selector/delay/network-idle waits, request and resource blocking, headers, cookies, user agents, Authorization, timezone, geolocation, transparent backgrounds, image resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification. Parameters used by other screenshot APIs also work, which can simplify migration.
See the ScreenshotNeo documentation for authentication and options. For a quick capture:
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}`);The Free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan. Create a free ScreenshotNeo account to try it.
Frequently Asked Questions
Will increasing a Rails request timeout fix a stuck wkhtmltopdf process?
No. It only allows the request to wait longer. First make the standalone conversion terminate, then correct the renderer option, asset, binary, or architecture that caused the wait.
Can I keep Wicked PDF templates while moving to another renderer?
Often, but fidelity is template-dependent. Audit JavaScript, CSS features, local assets, headers, and page-break rules, then compare representative PDFs before changing production.
Why should stderr be retained in production diagnostics?
The child process frequently reports missing assets, invalid options, or runtime failures only on stderr. Discarding it turns an actionable error into an unexplained timeout.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Is an Apple-Silicon Mac required to run an arm64 wkhtmltopdf build?
No. Intel Macs require an x86_64-compatible executable; Apple-Silicon Macs can run native arm64 software and, where configured, Intel software through Rosetta. The executable and Ruby process must be used with a compatible, intentional architecture.
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.
