Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If WickedPDF renders correctly in development but loses styles, images, fonts, or layout in production, compare the actual wkhtmltopdf executable and build, production asset URLs, host libraries and fonts, JavaScript timing, and PDF options. WickedPDF is a Rails wrapper: the separate wkhtmltopdf process must be able to load and render the HTML and its resources in the production environment. There is no single fix that applies to every deployment; start by collecting comparable output and logs, then change one verified difference at a time.
Why the same WickedPDF view can produce different PDFs
WickedPDF saves HTML and assets to temporary files and invokes wkhtmltopdf, an external command-line renderer. A Rails page that looks right in a browser therefore does not prove that the renderer can reach the same stylesheets, images, scripts, or fonts. The executable also runs with the production host’s operating system, libraries, process permissions, and configuration. The WickedPDF README documents this wrapper behavior and its asset helpers; wkhtmltopdf describes its rendering engine and platform packages at its project site.
First identify the visible symptom: missing styling or images usually points toward resource loading; altered line breaks or pagination can involve fonts or scaling; missing dynamically inserted content can involve JavaScript completion; a process error may indicate an incompatible binary or runtime dependency. These are diagnostic clues, not proof of cause. The app’s versions, operating systems, logs, and PDFs determine the fix.
Free tools Windows power users keep installed
One-click scans. No signup required.
Collect a reproducible comparison before changing settings
Generate a PDF from the same record and input data in development and production. Save the output files, rendered HTML where available, command-line options, and renderer output. In production, run checks in the same container or host and with the same user and environment as the Rails process—not just from a developer shell that may find another executable on PATH.
#1 Best Overall
- Record the Rails, WickedPDF, and wkhtmltopdf versions in each environment.
- Find the executable configured for WickedPDF, including
exe_path, and run that exact binary’s version command in the production runtime context. - Record the operating-system or container base, architecture, relevant libraries, and installed font families.
- Capture stdout and stderr, the generated HTML, the renderer options, and whether each referenced resource loaded.
- Compare page dimensions, page breaks, extracted text, image presence, and font appearance across the PDFs.
The upstream wkhtmltopdf usage manual documents version and diagnostic options, although flags can vary by build. Check the actual binary’s supported options before relying on one.
Check production assets from wkhtmltopdf’s point of view
Inspect the generated HTML and resolved URLs
Use the app’s HTML-preview mode if available, or otherwise inspect the HTML WickedPDF passes to the renderer. Confirm that the stylesheet, image, JavaScript, and font URLs are the URLs intended for production. A relative URL that resolves in a browser page may not resolve from a temporary HTML file or from the renderer’s process context. Authentication requirements, asset-host configuration, network egress, protocol mismatches, and file permissions can all affect whether a resource is reachable.
WickedPDF documents helpers such as wicked_pdf_stylesheet_link_tag, wicked_pdf_image_tag, and wicked_pdf_javascript_include_tag for PDF views. Use the helpers or appropriate absolute references for the way your app serves its assets; then inspect the resulting HTML rather than assuming the helper generated a usable production URL.
Recommended Free Tools
Verify compilation and deployed asset manifests
Production commonly serves precompiled assets rather than compiling them on demand. WickedPDF specifically warns that when Rails has config.assets.compile = false, development and production asset behavior differs, and recommends precompiling assets used by PDF views. Its README explains that this can make a PDF appear to work in development while assets fail to load after deployment.
- List every stylesheet, script, image, and custom font the PDF view references.
- Confirm that the deployed asset manifest contains those assets and that the digest names in the generated HTML match the deployed files.
- Check that the configured asset host and scheme are correct from the production renderer’s network context.
- Where a resource is local, verify its path and permissions; where it is remote, verify access without weakening network or authentication controls.
For failures that remain unclear, enable the logging and load-error diagnostics supported by the installed wkhtmltopdf build. The manual documents logging and load-error handling; consult its options and confirm support with the production executable before changing behavior.
Compare the binary, operating system, and runtime libraries
Two environments can report the same wkhtmltopdf version string but still use different packages or builds. Compare the configured executable path, package provenance or build variant, and supported options, not just the command name. WickedPDF documents setting an explicit executable path when wkhtmltopdf is not on the web server’s PATH.
The upstream wkhtmltopdf platform guidance cautions that a nominally static Linux build still depends on runtime libraries and system configuration. It discusses distribution-specific libc differences, fontconfig and freetype2, and notes that Alpine uses musl rather than glibc. A binary packaged for one distribution may not behave or run correctly in another environment.
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 reinstall- Compare the production image or OS release with development, including libc and required libraries.
- Use a wkhtmltopdf package intended for the production distribution and architecture, and verify its dependencies in that runtime.
- Check whether the web process can execute the binary and access its temporary files.
- Compare actual supported flags if options are ignored or rejected; do not assume every build exposes identical controls.
Check fonts before tuning layout
Different installed fonts can alter glyph coverage, character widths, line breaks, and therefore pagination. Compare the fonts named in the PDF CSS with the families installed and discoverable in each environment; check font configuration where relevant. The upstream platform guidance identifies fontconfig and freetype2 as runtime considerations, but it does not establish one universal font package or prove that a font mismatch explains a particular incident.
If a fallback font appears in production, install or package the intended font in the production runtime and confirm that wkhtmltopdf can discover it. Re-render the same input and inspect text wrapping and page breaks before changing zoom or margins, which can conceal a font problem while introducing other layout differences.
Make JavaScript completion deterministic
If a page inserts content with JavaScript, the renderer may capture before that work finishes. The wkhtmltopdf manual documents --javascript-delay and --window-status; WickedPDF also passes renderer options. Prefer a completion signal that the page sets only when required content is ready, using a supported window-status mechanism, rather than selecting an arbitrary long delay. A delay can be useful as a diagnostic or where no reliable signal is available, but it adds rendering time and is not proof that every asynchronous request completed.
Compare whether JavaScript is enabled, whether the production page can fetch its data and scripts, and whether the relevant options are identical in both environments. If scripts fail, inspect renderer logs and resource access rather than only increasing the wait.
Compare scale, page setup, and print behavior
Review the options that determine physical layout: DPI, zoom, smart shrinking, page size, margins, orientation, and whether print or screen media styles are used. The wkhtmltopdf manual documents zoom, smart shrinking, and print-media controls. Small changes can move content across page boundaries, so compare the exact values passed by the application in each environment.
The WickedPDF README gives a platform example: Linux may print at 75 dpi while Windows commonly uses 96 dpi, and it shows 0.78125 (75/96) as a zoom example for matching those stated values. These are documentation examples, not guarantees for every machine or a universal correction. Test a DPI or zoom adjustment only after confirming a platform-scale difference; apply it consistently and verify the resulting page dimensions and pagination.
Use a one-variable-at-a-time troubleshooting sequence
- Reproduce: Render the same input and record the environment and all options.
- Classify: Decide whether the difference is missing content, typography/layout, timing, or a process failure.
- Check resources: Inspect generated HTML and verify each production URL, asset manifest entry, font, permission, and network path.
- Check runtime: Verify the exact binary, build, OS, libraries, and process user.
- Check behavior options: Compare JavaScript readiness, media mode, page setup, DPI, zoom, and shrinking.
- Change one confirmed variable: Re-render identical input, preserve the before-and-after PDFs and logs, and keep the change only if it addresses the observed cause.
This process narrows the diagnosis without treating a workaround as a root-cause fix. The useful outcome is a specific difference—such as an absent precompiled stylesheet or unavailable font—and a narrowly scoped correction.
Common symptoms, likely causes, and fixes
| Symptom | What to check | Practical next step |
|---|---|---|
| CSS missing only in production | Generated stylesheet URL, asset host, precompiled file and digest, network access | Precompile the PDF assets, correct the URL or host configuration, and confirm the renderer can fetch the exact resource. |
| Images missing or intermittent | Resolved image URLs, local-file permissions, remote access, load-error logs | Use a renderer-accessible path and enable local access only for the intended files if the setup requires it. |
| Different line breaks or page count | Installed fonts, font discovery, DPI, zoom, smart shrinking, page dimensions | Match fonts and compare the exact scale and page options before adjusting layout. |
| Dynamic content absent | JavaScript enabled, script/data requests, completion condition, delay or window-status option | Wait on a deterministic readiness signal or use an appropriate supported delay, then inspect logs for failed requests. |
| Renderer exits or rejects an option | Configured executable, build, runtime dependencies, supported flags, permissions | Run the configured binary in the app’s production context, check its version and dependency compatibility, then use options supported by that build. |
Security matters when fixing resource access
Do not respond to missing assets by broadly allowing local-file access or unrestricted URL fetching. The server-side HTML-to-PDF process may load files or URLs, so untrusted HTML, CSS, or JavaScript can create risks. WickedPDF’s README recommends sanitizing user-generated markup or preventing requests to internal IP addresses and hostnames. Scope file access to the required assets and constrain remote requests according to the app’s security model.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server, not a drop-in WickedPDF renderer. It can help capture a web page for visual checks of rendered HTML and loaded assets; it does not establish that a WickedPDF PDF will paginate or print identically. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card required.
Questions that depend on your deployment
Without the Rails, WickedPDF, and wkhtmltopdf versions, production OS, font inventory, logs, and matching output PDFs, the exact cause cannot be identified in advance. The diagnostic steps above identify what to compare; the fix should be based on the difference demonstrated in the affected deployment.
Frequently Asked Questions
Does the 0.78125 zoom value fix every Linux-versus-Windows difference?
No. WickedPDF documents it as an example based on the stated 75 dpi and 96 dpi values. Verify the actual platforms and output before using it.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Can ScreenshotNeo replace WickedPDF for matching PDF pagination?
No. ScreenshotNeo can capture a website for visual checks, but its screenshots do not validate WickedPDF’s PDF layout or pagination.
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.
