When Wicked PDF fails, check the integration in layers: the wicked_pdf gem, the separate wkhtmltopdf executable, the executable path visible to the Rails process, asset URLs, renderer build capabilities, and only then permissions or template code. Installing the gem alone does not install a working PDF renderer.
Understand what Wicked PDF actually runs
Wicked PDF is a Rails wrapper around the wkhtmltopdf shell utility. Rails renders your view, then the wrapper starts that external executable to convert HTML into a PDF. The two components have separate failure modes. The official Wicked PDF README documents adding the gem, running Bundler, generating an initializer, and installing a wkhtmltopdf binary. Its version-specific compatibility notes should not be treated as a current guarantee without checking the release and binary you use.
- Rails layer: the gem must be in the application bundle and configured.
- Process layer: a usable
wkhtmltopdfexecutable must exist in the deployed environment. - Input layer: the renderer must be able to fetch your stylesheets, images, fonts and JavaScript.
- Capability layer: your binary’s version and Qt build must support every option you pass.
- Runtime layer: the Rails user must be able to execute the binary and use the specific temporary paths involved.
Keep these layers separate while debugging. A successful bundle install does not prove that PDF conversion can start.
Install and verify both dependencies
Declare the Rails wrapper
Add Wicked PDF to the Gemfile, install the bundle, and generate the initializer using the commands documented by the project:
#1 Best Overall
- INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
- COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
- ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
- HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs
bundle add wicked_pdf
bundle install
bin/rails generate wicked_pdfIf your application uses a Gemfile group for production, ensure the deployment process installs that group. Restart the Rails process after changing the bundle or initializer.
Install wkhtmltopdf separately
The wrapper does not supply the renderer. The README describes wkhtmltopdf-binary as a convenient choice for many Linux and macOS setups, but binary availability and compatibility depend on your platform and release. Alternatively, install a distribution package or a vetted binary according to your operating system’s policy. Confirm the executable in the same container, VM, service unit or release directory that runs Rails:
command -v wkhtmltopdf
wkhtmltopdf --version
wkhtmltopdf --helpOn Windows, use the equivalent executable lookup and run the binary from the account that hosts Rails. Do not rely on a path that exists only on your workstation.
Fix “wkhtmltopdf executable not found”
Test the deployed runtime, not your shell
Web servers often have a smaller PATH than an interactive login shell. A command that works over SSH can still fail under Puma, Passenger, Sidekiq or a container entrypoint. Log the effective environment from the Rails process, or run a one-off command inside the production container:
ruby -e 'puts ENV.fetch("PATH", "")'
command -v wkhtmltopdfCheck file existence and execute permission at the returned location. If the command is absent, install the binary in the image or host and redeploy.
Set exe_path when PATH lookup is unreliable
Configure the absolute path in the generated Wicked PDF initializer. The exact initializer shape can vary by release, so preserve the file’s existing structure and set the documented option:
Rank #2
- CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
- INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
- PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
- ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴
WickedPdf.config = {
exe_path: "/usr/local/bin/wkhtmltopdf"
}Use the path visible inside the deployment environment, not a macOS path copied from development. Historical reports, including issue #758, show that path discovery can fail in particular Bundler and runtime arrangements; that report is an example, not a universal diagnosis.
Read Bundler errors literally
If the exception says wkhtmltopdf-binary is not in the bundle, inspect the Gemfile, lockfile and deployment install step. A historical report in issue #996 demonstrates this class of executable-discovery and Bundler error. Fix the dependency in the environment that actually launches Rails, then restart the process.
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 matchFix CSS, images and JavaScript that disappear
wkhtmltopdf runs outside the browser and outside the normal Rails asset request flow. Relative URLs that work in Chrome may resolve nowhere when the external renderer loads the HTML.
Use absolute, reachable asset URLs
Generate URLs with the correct scheme and host for the deployment, and make sure the renderer can reach them from its network namespace. Check HTTPS certificates, private DNS, authentication and firewall rules. Prefer the Wicked PDF helpers documented in the official README for stylesheets, images and JavaScript rather than hand-building paths.
- Use an absolute URL or a helper that emits one.
- Confirm the asset returns a successful response from the Rails host or container.
- Verify that credentials, cookies or signed URLs are available if assets are private.
- For local files, confirm the path exists inside the renderer’s filesystem.
Start with a minimal view containing plain text, one stylesheet and one image. Add complex JavaScript only after that baseline renders. If you run an older Rails release, check whether it requires explicit PDF MIME type registration, as noted in the README.
Distinguish an asset problem from a renderer problem
Run the generated HTML URL through a normal browser and inspect the response separately. Then capture a PDF with external assets temporarily replaced by inline styles or a data URL. If inline content appears but remote content does not, investigate URL reachability and renderer access rather than changing Rails templates.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
- SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
- INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
- KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
- PREMIUM SUPPORT - Strong technical expertise to solve issues faster
- THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.
Fix rejected options and footer or header failures
Wicked PDF passes command-line switches to wkhtmltopdf. Supported flags vary by version and build. Before changing templates, inspect the installed executable’s own help output and version:
wkhtmltopdf --version
wkhtmltopdf --extended-helpTry the smallest command that reproduces the failure, then add options one at a time. An unpatched-Qt build may reject a footer or header switch that another build accepts; issue #953 records that kind of report. Do not assume that a flag documented for a different binary is available in yours. Replace the package or adjust the option only after confirming the build’s capabilities.
Investigate temporary files and permissions precisely
Permission errors can involve the executable, a configured temporary directory, an output destination or an asset file. Capture the complete exception and identify the exact path named in it. Check:
- the Rails service user can execute the binary;
- the temporary directory exists and permits the required read/write operations;
- the destination directory exists and is writable when you save a PDF;
- container security policies, read-only filesystems and volume mounts are not blocking the path.
Do not assume the web server’s home directory must be writable. The discussion in issue #758 cautions against that broad assumption; test the precise path and executable lookup shown by the error.
A repeatable diagnostic procedure
- Reduce the case. Render a plain HTML view to PDF with no custom switches.
- Confirm the bundle. Run
bundle exec ruby -e 'require "wicked_pdf"; puts WickedPdf'in the deployed release. - Confirm the executable. Run
wkhtmltopdf --versionin the same runtime and user context. - Confirm the path. Compare
command -v wkhtmltopdfwithexe_path, if configured. - Capture the command output. Preserve stderr; messages about missing libraries, rejected switches and inaccessible URLs identify different fixes.
- Add assets. Test an absolute stylesheet URL, then images and scripts individually.
- Add options incrementally. Headers, footers, JavaScript delays and page settings should be tested separately against the installed build.
- Check permissions last. Inspect only the path named by the error and the service account’s access.
Common symptoms and targeted fixes
| Symptom | Likely layer | First fix |
|---|---|---|
| “No such file” or executable not found | Binary/path | Install wkhtmltopdf in the deployment environment or set its absolute exe_path. |
| Gem loads but conversion never starts | Wrapper versus executable | Verify the binary independently with --version. |
| Text appears but CSS or images do not | Asset access | Use absolute URLs or documented Wicked PDF helpers and test reachability from the runtime. |
| Unknown or rejected footer/header option | Version/build | Read the binary’s help and replace or reconfigure an incompatible build. |
| Permission or temporary-file exception | Runtime filesystem | Check the exact named path, service user and container mounts. |
Security: never render untrusted HTML directly
The wkhtmltopdf project warns on its Downloads page: “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 submitted HTML, CSS and JavaScript as hostile. Sanitize it, restrict what URLs and protocols can be fetched, isolate the renderer where practical, and avoid passing arbitrary command-line values from users.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is a reliable website image or PDF rather than a Rails-local renderer, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP or PDF. It accepts cookie banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server exposes take_screenshot, get_page_info and capture_pdf to 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 documentation for options such as full-page capture, element selectors, device and viewport settings, retina scale, PDF paper and margins, custom CSS or JavaScript, waits, blocked resources, cookies, headers, geolocation, caching, signed links, asynchronous webhooks, bulk capture and usage reporting. The free plan includes 1,000 screenshots monthly with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Rank #4
- Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
- No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
- Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
- Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
- The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art
FAQ
Does installing wicked_pdf install wkhtmltopdf?
No. Install and verify the separate executable in the environment that runs Rails.
Why does a PDF work locally but fail in production?
Production may have a different PATH, binary location, Qt build, network access, service user or filesystem layout. Compare those conditions directly.
Should I switch binaries immediately when an option fails?
First inspect wkhtmltopdf --version and help output. The option may be unsupported by the installed build, or the application may be passing it incorrectly.
Can I render user-submitted HTML with Wicked PDF?
Not safely without strong sanitization and isolation. The wkhtmltopdf project explicitly warns that untrusted HTML or JavaScript can lead to server takeover.
Frequently Asked Questions
Which component should I troubleshoot first?
Verify the deployed bundle and then run the separate wkhtmltopdf executable directly; this distinguishes Rails integration errors from renderer installation errors.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsWhat is the safest first test?
Generate a plain-text PDF with no remote assets or optional switches, then add one dependency at a time.
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.
