How to Configure the wkhtmltopdf Path in a Ruby on Rails Application
Set Wicked PDF's wkhtmltopdf path in Rails, verify production deployments, fix asset and permission errors, and compare hosted capture options.

Direct answer: Set Wicked PDF’s exe_path to the absolute path of an executable wkhtmltopdf binary in config/initializers/wicked_pdf.rb, then restart Rails. For example:
# config/initializers/wicked_pdf.rb
WickedPdf.configure do |config|
config.exe_path = '/usr/local/bin/wkhtmltopdf'
config.enable_local_file_access = true
end
The path must exist, be executable, and be visible to the same user and environment that runs Rails. If the binary is installed through the wkhtmltopdf-binary gem, let Wicked PDF discover it or set the resolved absolute path explicitly. A render-level wkhtmltopdf: option can override the global setting for one PDF.
1. Install Wicked PDF and wkhtmltopdf
Add the integration gem:

# Gemfile
gem 'wicked_pdf'
bundle install
Install a wkhtmltopdf executable using one of these approaches:
| Approach | When it fits | Things to verify |
|---|---|---|
wkhtmltopdf-binary gem |
You want the executable packaged with your application dependencies on supported Linux or macOS setups. | The gem is in the deployed bundle, the binary is extracted, and the deployment user can execute it. |
| System package or vendor binary | You control the host image, VM, or container and want an OS-managed install. | The exact path, shared libraries, fonts, permissions, and architecture match the Rails runtime. |
The Wicked PDF README describes wkhtmltopdf-binary as a convenient distribution option and documents initializer configuration (Wicked PDF README). The wkhtmltopdf project publishes platform packages and its security guidance on its downloads page (wkhtmltopdf downloads).
Using the binary gem
If you choose the gem, add it to the Gemfile group that is installed in production. A common mistake is putting it in a development-only group, so production Bundler never installs it. After deployment, confirm the gem and executable are present before booting the web process.
# Gemfile
gem 'wicked_pdf'
gem 'wkhtmltopdf-binary'
Some environments require a platform-specific binary gem. Lock dependencies in Gemfile.lock and build on the same CPU and libc family used in production, or use a container image with the required libraries.
2. Configure the global executable path
Generate the initializer if you want the gem’s template, or create it manually:
bin/rails generate wicked_pdf
Edit config/initializers/wicked_pdf.rb and use an absolute path:
WickedPdf.configure do |config|
config.exe_path = '/usr/local/bin/wkhtmltopdf'
config.enable_local_file_access = true
end
exe_path is the setting that controls which process Wicked PDF launches. The initializer loads while Rails boots, so restart every web, job, and console process after changing it. Keep environment-specific paths in deployment configuration when hosts differ:
# config/initializers/wicked_pdf.rb
WickedPdf.configure do |config|
config.exe_path = ENV.fetch('WKHTMLTOPDF_PATH', '/usr/local/bin/wkhtmltopdf')
config.enable_local_file_access = true
end
# shell or container environment
export WKHTMLTOPDF_PATH=/app/vendor/bin/wkhtmltopdf
Use enable_local_file_access only when your templates need local stylesheets, images, or fonts. Local file access expands what the renderer can read, so keep user-controlled HTML and URLs out of privileged rendering contexts.
3. Verify the path before rendering
Check the binary as the Rails deployment user, not only as your login account:
command -v wkhtmltopdf
ls -l /usr/local/bin/wkhtmltopdf
/usr/local/bin/wkhtmltopdf --version
/usr/local/bin/wkhtmltopdf about:blank /tmp/wkhtmltopdf-check.pdf
In a Rails console, ask Wicked PDF which executable it resolved:
bin/rails console
WickedPdf.new.send(:find_wkhtmltopdf_binary_path)
Then verify the returned path exists and is executable:
path = WickedPdf.new.send(:find_wkhtmltopdf_binary_path)
File.file?(path) && File.executable?(path)
If this returns false or raises an error, inspect the deployment user’s PATH, Bundler groups, mounted volumes, and container architecture. A binary visible during an image build may not be present in the final runtime image.
4. Render a PDF and override the path when needed
A controller action can use Wicked PDF normally:
class InvoicesController < ApplicationController
def show
@invoice = Invoice.find(params[:id])
render pdf: "invoice-#{@invoice.id}", template: 'invoices/show'
end
end
For a one-off render, pass the executable directly. This is useful during a migration or when two binaries are installed:
render pdf: 'file_name',
wkhtmltopdf: '/opt/wkhtmltopdf/bin/wkhtmltopdf'
The per-render option takes precedence for that call; the initializer remains the default for every other render.
5. Make assets work outside the Rails process
wkhtmltopdf runs as a separate process. Relative URLs that work in a browser can fail when the renderer has no meaningful request host, cannot resolve an asset, or is blocked from local files. Prefer absolute asset URLs in production and use Wicked PDF helpers where appropriate:
<%= wicked_pdf_stylesheet_link_tag 'invoices' %>
<%= wicked_pdf_image_tag @invoice.logo_url %>
<%= wicked_pdf_javascript_include_tag 'application' %>
For remote assets, ensure the renderer can reach the hostname from the production network and that TLS certificates are trusted. For local assets, enable local file access and confirm the Rails process can read the files. Fingerprinted asset names must match the files shipped in the release.
6. Deployment patterns
Linux host or VM
- Install the package or copy a vetted binary.
- Record the absolute path in
WKHTMLTOPDF_PATH. - Install gems with the production bundle, including
wkhtmltopdf-binaryif selected. - Run the console verification as the service account.
- Restart web and background workers.
Docker
Install wkhtmltopdf in the final image stage, not only in a builder stage. Copy fonts and shared libraries as well as the executable. Keep the path stable, for example /usr/local/bin/wkhtmltopdf, and set the environment variable at runtime. Run a smoke render during image validation.
Heroku-style buildpacks
A buildpack or binary gem can provide the executable, but Bundler must install it in the slug. Do not assume a shell path from your laptop exists in the dyno. Print the resolved path in a one-off console and check execute permissions.
7. Troubleshooting checklist
| Symptom | Likely cause | Fix |
|---|---|---|
No wkhtmltopdf executable found |
Wrong path, missing gem, or PATH differs for the service. |
Set an absolute exe_path; run the console lookup and install the production Bundler group. |
| Works locally, fails in production | Binary, libraries, fonts, or permissions are absent in the production image. | Run --version and a smoke render as the Rails user inside the deployed environment. |
| Permission denied | File lacks execute permission or a parent directory is inaccessible. | Grant execute permission and directory traversal to the service account; verify with namei -l. |
| PDF has missing CSS or images | Relative URLs, inaccessible hostnames, or local file access disabled. | Use absolute URLs or Wicked PDF asset helpers; enable local access only when required. |
| Blank pages or timeouts | JavaScript is still running, remote resources are slow, or the page requires browser features wkhtmltopdf does not support. | Reduce blocking scripts, make assets reachable, increase render timeouts in your job wrapper, or choose a browser-based renderer for that page. |
Bundler cannot find wkhtmltopdf-binary |
The gem is excluded by a group or the lockfile was built for another platform. | Move it into an installed group, regenerate the lockfile for the target platform, and redeploy. |
| Different output after deploy | Different binary versions, fonts, locale, or timezone. | Pin the binary and fonts in the image; set locale and timezone explicitly; compare --version output. |
8. Security requirements
wkhtmltopdf executes outside Rails and processes HTML, CSS, JavaScript, and network resources. The wkhtmltopdf project warns: “Do not use wkhtmltopdf with any untrusted HTML”; sanitize user-supplied HTML and JavaScript before rendering (official security guidance). Run the process with least-privilege filesystem and network access, avoid passing secrets in HTML, and isolate rendering jobs when input can be influenced by users.
9. Performance, reliability, and cost
Each PDF starts an external process, so process startup, page loading, asset downloads, and font discovery contribute to latency. Reuse a warm worker process where your job system allows it, keep templates and assets small, and avoid rendering the same document repeatedly when a cached artifact is valid. Set bounded job timeouts and retries; retries should be idempotent and should not create duplicate records.
Pinning one binary and one font set improves reproducibility. Monitor exit status, stderr, render duration, and output size. Treat a zero-byte or unexpectedly small PDF as a failed job even if the process exits successfully. wkhtmltopdf itself has no per-render API charge; your operational cost comes from CPU, memory, storage, and any hosting or queue time used by the renderer.
10. When a hosted screenshot API is a better fit
If the goal is a website screenshot rather than a server-generated PDF, maintaining a browser binary, fonts, sandbox, retries, and asset networking can be unnecessary. ScreenshotNeo provides a GET endpoint that returns PNG, JPEG, WebP, or PDF and exposes an MCP server for AI clients.

Or skip the browser setup
Use the do-it-yourself Rails setup above when you need full control of a local renderer. For a hosted capture, call ScreenshotNeo directly (see the API documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
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)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
require('fs').writeFileSync('shot.webp', Buffer.from(await res.arrayBuffer()));
ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and whether it was billed. The MCP server includes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. Plans include 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
FAQ
Where does Wicked PDF look for wkhtmltopdf?
It checks configured and discoverable locations. Use exe_path with an absolute path when you need deterministic behavior, then confirm the resolved value from a Rails console.
Can I configure different binaries per environment?
Yes. Read WKHTMLTOPDF_PATH in the initializer, or pass wkhtmltopdf: on an individual render.
Why does a PDF work in development but not production?
The production user or container may lack the executable, shared libraries, fonts, network access, or permission to read assets. Verify all of them inside the deployed runtime.
Should I enable local file access?
Enable it only for templates that need local files, and never combine it with unsanitized user HTML.
Can wkhtmltopdf render every modern web page?
No. It may fail on pages that depend on browser APIs or long-running JavaScript. Simplify the page or use a browser-based capture service for those cases.


