What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
When PDFKit fails in a Rails 4 app, first identify which layer is failing: the Ruby gem, the separate wkhtmltopdf executable, or the renderer’s access to page assets. Installing the gem does not install the renderer. Test wkhtmltopdf under the same account and environment as Rails, then configure its absolute path if PDFKit cannot find it. If a PDF is created but looks incomplete, troubleshoot asset URLs and server concurrency instead of reinstalling the gem.
How PDFKit installation failures break down
PDFKit is a Ruby wrapper; wkhtmltopdf is the external program that turns HTML into a PDF. They are separate dependencies, so a successful bundle install confirms neither that the executable exists nor that Rails can run it. The PDFKit README lists Rails 4.2 among supported versions and instructs users to install wkhtmltopdf separately. That specific support listing should not be read as evidence that every Rails 4 release or every operating system combination is supported.
Use the symptom to choose what to test. A Bundler error points to the Ruby dependency layer. “Cannot find wkhtmltopdf” usually means command discovery or environment differences. A process that starts but fails before making a PDF points to the executable or its operating-system dependencies. A valid PDF with missing styling or images is a rendering or asset-access problem.
Check the gem and renderer independently
1. Confirm the app’s Ruby and Bundler setup
Keep pdfkit in the application’s Gemfile, and run Bundler with the Ruby version used by the app. For example:
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 →Clear out junk files and repair common Windows errorsFree Scan →#1 Best Overall
bundle exec ruby -e 'require "pdfkit"; puts "PDFKit loaded"'If that command fails, resolve the Ruby or Bundler error first. If it succeeds, continue: loading the wrapper does not prove that wkhtmltopdf is installed.
2. Run the executable as the Rails service user
Switch to, or otherwise run commands as, the account that launches Rails (for example, the application’s service account). Use that account’s environment, including its PATH. Test the version and a minimal conversion:
wkhtmltopdf --version
printf '<html><body><h1>PDF test</h1></body></html>' > /tmp/pdfkit-test.html
wkhtmltopdf /tmp/pdfkit-test.html /tmp/pdfkit-test.pdf
ls -l /tmp/pdfkit-test.pdfThe expected result is a version string followed by a non-empty PDF file. If the command is not found or cannot execute, do not debug Rails rendering yet: fix the OS package, executable permissions, architecture, or missing runtime libraries first. The wkhtmltopdf project’s downloads information identifies platform-specific packages and notes fontconfig and freetype2 as runtime factors.
Make PDFKit find the right executable
PDFKit tries to discover the command by running which wkhtmltopdf. As the PDFKit maintainers explain, “PDFKit will try to intelligently guess at the location of wkhtmltopdf by running the command which wkhtmltopdf.” That lookup can fail when the service has a different PATH from your interactive shell, or when the binary is in a nonstandard, Windows, or container-specific location.
Free tools Windows power users keep installed
One-click scans. No signup required.
Find the executable path in the Rails service environment with which wkhtmltopdf, then set that absolute path in the initializer:
# config/initializers/pdfkit.rb
PDFKit.configure do |config|
config.wkhtmltopdf = '/absolute/path/to/wkhtmltopdf'
endReplace the example path with the actual executable location on the host. Restart the Rails process after changing an initializer. An explicit path is a useful diagnostic: if PDFKit still fails, the issue is less likely to be command discovery and more likely to be execution, dependencies, permissions, or rendering.
Check architecture, libraries, fonts, and permissions
A binary can exist and still fail to start. Confirm that the package or release matches both the host operating system and CPU architecture. A historically reported Rails setup failure involved choosing the wrong binary architecture; the practical check is the executable itself, not the Rails version number or the gem’s presence.
- Architecture mismatch: install a build for the server’s CPU and operating system.
- Missing shared libraries: inspect the operating system’s loader output for missing dependencies, then install the matching libraries using the host’s package manager.
- Fonts or rendering libraries: check that fontconfig and freetype2 are available and that the service can access installed fonts.
- Permissions: ensure the Rails service account can execute the file and traverse its parent directories.
The wkhtmltopdf downloads page records stable version 0.12.6, dated June 11, 2020. That is a release-history fact, not a guarantee that this binary runs on every newer distribution. Validate the chosen release on the actual host rather than assuming a package works because it installed successfully.
Recommended Free Tools
Fix missing CSS, images, or other page assets
If the PDF is produced but lacks styling or images, the renderer may not be able to resolve the asset references in the HTML. Relative paths that work in a browser can fail when a renderer loads a generated document outside the usual page context. Use absolute file paths or complete URLs for resources the renderer must fetch.
Rank #4
When assets use the app’s hostname, configure PDFKit’s root_url if that hostname is not reachable from the renderer. Check reachability from the machine or container running wkhtmltopdf, not only from your workstation. Authentication, network rules, and host resolution can also mean that a URL available to a logged-in browser is unavailable to the separate renderer.
To isolate the problem, try a small HTML document with one known reachable image or stylesheet. If the local test works but the app’s PDF does not, inspect the generated HTML and each resource URL. If remote assets fail only on the server, investigate server-side connectivity and hostname resolution before changing Rails code.
Unstick generation that hangs in development
A development request can deadlock if a single-thread server is handling the PDF request while wkhtmltopdf calls back to the same server for CSS, images, or other assets. The request occupies the only server thread; the asset request waits for that thread, and PDF generation waits for the asset. The PDFKit README describes this as a “Single thread issue” common in development environments that run a single server process.
Best Value
Use a server configuration with multiple workers or processes; the PDFKit README gives Unicorn as an example. Another option is to embed required resources in the HTML so the renderer does not need to call back into the app. If generation hangs only in development, test this concurrency and asset-access path before replacing the executable.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Return the PDF with the correct response type
If the response contains PDF bytes but the browser displays them as text or renders the inline page incorrectly, set the response content type to application/pdf. This is a response-header issue, not evidence that PDFKit failed to install. Verify the generated file independently and inspect the HTTP response’s content type when the file itself is valid.
Use the failure to choose the next fix
| What you observe | Likely layer | Next check |
|---|---|---|
| Bundler cannot load PDFKit | Ruby dependency | Run Bundler with the app’s Ruby version and resolve the gem error. |
| “wkhtmltopdf” is not found | Command discovery | Check the service account’s PATH and set an absolute initializer path. |
| The command exists but will not start | Operating system | Check architecture, permissions, shared libraries, fontconfig, and freetype2. |
| A PDF is made, but assets are absent | Rendering and URLs | Use absolute paths or complete URLs; check root_url and renderer reachability. |
| Only development generation hangs | Server concurrency | Check for a single-thread callback deadlock; use multiple workers or embed resources. |
| PDF bytes display incorrectly in the browser | HTTP response | Set the response content type to application/pdf. |
Or skip the browser setup
If your immediate goal is a PDF of a page that the service can reach, rather than fixing Rails PDFKit itself, ScreenshotNeo offers a separate URL-based capture route. It does not repair a broken wkhtmltopdf installation or replace PDFKit inside the Rails app. Its API accepts a URL and can return a PDF; see the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o page.pdfScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots, and yearly billing gives two months free. Every feature is available on every plan. Visit ScreenshotNeo for details, or sign up free for 1,000 screenshots a month with no card.
Keep the input safe
Do not pass untrusted HTML or JavaScript to wkhtmltopdf without sanitizing it. The wkhtmltopdf project warns that unsafe user-supplied HTML or JavaScript can enable complete takeover of the server running the renderer. Treat document generation as a security boundary: accept only content you trust or have appropriately sanitized.
Compatibility context for older Rails applications
The maintained PDFKit README currently lists Rails 4.2, 5.2, 6.0, 6.1, and 7.0 among its supported Rails versions. Its Rails 4.2 entry does not establish compatibility for every Rails 4 minor release or every operating-system package. RailsBump’s Rails 4.2 index lists numerous wkhtmltopdf-binary releases without declared Rails dependency constraints; the absence of a declared constraint is not proof that an embedded binary will run on a particular host. Test the executable in the target environment.
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.
