The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →If WickedPdf generates PDFs on your computer but fails on Heroku, the most likely cause is that the Heroku dyno cannot find the separate wkhtmltopdf executable. Install that binary as part of the Heroku build, verify its path on a dyno, and configure WickedPdf to use that exact path. If the PDF then renders but lacks styling or images, fix the asset URLs separately.
Why WickedPdf works locally but fails on Heroku
WickedPdf is a Ruby wrapper; it does not render the PDF itself. It invokes the external wkhtmltopdf command-line utility. Your development machine may already have that program installed or supplied by a development dependency, but a Heroku dyno is a separate Linux environment. The binary must be present in the deployed app and accessible to the process that generates PDFs. The WickedPdf project documentation describes the utility as the tool it uses to serve a PDF from HTML.
That distinction explains two common symptoms: an executable-not-found error means the dyno cannot locate the binary; a PDF that exists but looks unstyled usually points instead to CSS, image, or other asset URLs that the renderer cannot access.
Choose how to put wkhtmltopdf on the Heroku dyno
Use one delivery method, then verify the executable installed by that method. Avoid assuming a local gem shim, system PATH, or development install will carry over to Heroku.
#1 Best Overall
| Method | How it supplies the binary | What to check |
|---|---|---|
| Heroku buildpack | The buildpack downloads or supplies the executable during slug creation. | Confirm the buildpack is attached and correctly ordered, the download/version settings are valid, and the app stack is supported. The installed executable may be in a directory such as /app/bin, but verify its actual location on your dyno. |
Heroku-compatible gem such as wkhtmltopdf-heroku |
The gem provides a Heroku-compatible binary path through RubyGems. | Confirm the gem is in the deployed bundle and use the path it exposes; do not presume a command shim is on PATH. See the gem project. |
Buildpacks and gems have different provenance and path behavior; neither is universally correct for every app. Check that the chosen option supports your Heroku stack and the binary version you intend to run. Older buildpacks may document stack limitations. If you change a buildpack’s download URL or version, clear the Heroku build cache and redeploy so the old binary is not reused. Heroku’s buildpack documentation specifically advises cleaning the repository cache when updating a buildpack version.
Install, deploy, and verify the binary
- Choose and configure a single delivery method. Attach the selected buildpack to the app or add the compatible gem to the application bundle and lockfile. Follow that method’s current instructions for your app stack.
- Deploy the application. A local install is not evidence that the slug contains the executable. Redeploy after changing the buildpack or bundle.
- Check PATH and version from a dyno. Run
heroku run which wkhtmltopdf, thenheroku run wkhtmltopdf --version. These commands test the deployed environment, not your workstation. - If PATH lookup fails, run the installed file directly. If your buildpack is expected to install it under
bin/, testheroku run bin/wkhtmltopdf -V. Use the verified absolute path in the initializer, rather than guessing from the buildpack’s expected layout. - Configure WickedPdf if necessary. Set
exe_pathexplicitly when the executable is not reliably found through PATH. The WickedPdf documentation supports this setting.
Set WickedPdf’s executable path
In config/initializers/wicked_pdf.rb, set exe_path to the exact location you verified on the dyno:
WickedPdf.configure do |c|
c.exe_path = '/app/bin/wkhtmltopdf' # replace with the path verified in the dyno
c.enable_local_file_access = true # needed when local files are read with wkhtmltopdf > 0.12.6
endThe example path is not guaranteed to match every buildpack, slug, or installation method. Substitute the path found in your app. If using a gem that exposes the executable through Gem.bin_path, follow that gem’s documented path mechanism rather than copying the example blindly.
enable_local_file_access is relevant when the renderer must read local files with wkhtmltopdf versions newer than 0.12.6. Enable it only when local-file access is part of your asset strategy; it does not make an inaccessible remote URL work, nor does it install the binary.
Free tools Windows power users keep installed
One-click scans. No signup required.
Make CSS and images available to the renderer
Once the command runs, asset loading is a separate problem. wkhtmltopdf runs outside the Rails process and needs URLs or file access it can resolve. Relative paths that work in a browser request may not resolve when the renderer processes the HTML.
Use absolute URLs for remotely served assets
Give CSS, JavaScript, and image references absolute URLs that the dyno’s renderer can reach. Check that the host and scheme are correct in production, and that the referenced resources do not require a browser session or inaccessible authentication. If an asset host is configured through environment variables, compare its deployed value with the local value.
Use WickedPdf asset helpers where appropriate
WickedPdf provides helpers for generating asset tags for PDF rendering. Use the helper tags recommended by the project for your Rails and WickedPdf versions instead of relying on relative browser paths. The WickedPdf README documents its asset handling guidance.
Allow local file access only for local-file assets
If your HTML points to files on disk rather than URLs, confirm those files exist in the deployed slug at the path the renderer receives. For versions newer than 0.12.6, local file access must be enabled for this approach. Local filesystem paths and remote absolute URLs are different strategies; turning on local access will not repair an incorrect URL or missing deployed file.
Diagnose common Heroku failures
| Symptom | Likely cause | What to do |
|---|---|---|
wkhtmltopdf not found or executable launch fails |
The binary is absent from the slug, not on PATH, or the configured path is wrong. | Run heroku run which wkhtmltopdf and check the version. If PATH lookup fails, run the verified file path directly and set c.exe_path to that location. |
wkhtmltopdf-binary is not in the bundle |
Bundler cannot resolve the gem or shim expected by the application, even if a system binary exists. | Inspect the Gemfile groups and lockfile to ensure the required gem is available in the deployed bundle. If supplying the executable by buildpack instead, configure WickedPdf to use that executable rather than relying on a missing gem shim. See the WickedPdf issue tracker for this class of Bundler mismatch. |
| The executable works locally but not on a dyno | The local machine and Heroku slug have different operating environments or installed programs. | Verify the binary from a one-off dyno, confirm the delivery method is deployed, and use the dyno’s path and version. |
| A PDF is produced but CSS or images are absent | The renderer cannot resolve relative paths, the production asset host differs, or local files are missing/inaccessible. | Use absolute reachable URLs or WickedPdf asset helpers; verify deployed asset-host configuration and local file locations. |
| A buildpack change appears to have no effect | The build cache may contain a previously downloaded binary, or the buildpack may not be attached or ordered as expected. | Confirm attachment and order, clean the Heroku build cache, and redeploy after changing the version or download URL. |
| Local output differs from production | Environment variables can differ between Heroku Local and deployed config vars. | Heroku Local reads .env; compare those values with the app’s Heroku config vars, especially asset-host or URL settings. See Heroku’s Running Apps Locally documentation, updated April 13, 2026. |
Deployment, reliability, and cost considerations
- Verify after every environment change. A passing local PDF test only validates the local binary and asset configuration. Run the executable and a representative PDF generation request against the deployed environment after changing the binary source, version, stack, or asset host.
- Keep the binary version intentional. A buildpack’s download URL and a gem’s packaged binary are distinct supply paths. Record which one the app uses and verify the resulting version on a dyno, especially after buildpack or stack changes.
- Account for cache behavior during changes. If a buildpack version or binary URL is changed but the dyno still appears to use an old executable, clear the build cache and rebuild.
- Keep rendering failures distinct from asset failures. First establish that the command runs; then diagnose resource access. This avoids changing Rails asset configuration to address an executable installation problem.
Or skip the browser setup:
If your task is taking a screenshot or PDF of a web page rather than generating a Rails view through WickedPdf, ScreenshotNeo provides a website screenshot API and MCP server. One GET request can return a screenshot or PDF, without installing a browser binary in your app.
Example cURL request:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for parameters. Cookie banners, popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. This is an alternative for capturing web pages, not a fix for a Rails PDF pipeline that must render application-specific HTML.
Sign up free for ScreenshotNeo: 1,000 screenshots a month, no card required.
FAQ
Should I install both the buildpack and the gem?
Choose one binary-delivery method unless a specific setup requires otherwise. Using one makes it clearer which executable path and version the dyno should run.
Recommended Free Tools
Does setting exe_path install wkhtmltopdf?
No. It tells WickedPdf where to find an executable that must already be present in the deployed environment.
Will enabling local file access fix missing images?
Only when the renderer is reading local files and the files exist at the referenced paths. For web-hosted assets, use reachable absolute URLs or the appropriate WickedPdf helpers.
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.
