If wkhtmltopdf cannot load a local stylesheet, image, or font, first check its local-file policy and the paths visible to the process that actually generates the PDF. The upstream CLI documentation describes local-file access as disabled by default: use --allow to permit only the required path, or --enable-local-file-access for broader access. For known assets, prefer the narrow allow-list and do not enable broad file access for untrusted HTML.
How wkhtmltopdf handles local files
wkhtmltopdf renders HTML and may need to read other resources referenced by that HTML: CSS, images, fonts, and stylesheets supplied separately. A local file can be present on disk and still fail to appear if the renderer is not allowed to read it, if the URL points somewhere else, or if the rendering environment cannot see the file.
The CLI reference documents --disable-local-file-access as the restrictive default. With that policy, a local input cannot read other local files unless they are explicitly permitted using --allow <path>. The broader --enable-local-file-access option permits local reads. These are access controls for the renderer, not a complete operating-system security boundary.
Choose the narrowest access that works
- Known asset directory: keep local access disabled and allow the specific directory or directories the document needs.
- Controlled, trusted input: broad access may be available with
--enable-local-file-access, but it grants more access than an asset-specific allow-list. - User-supplied or otherwise untrusted HTML: do not treat enabling local access as a fix. The project warns against rendering untrusted HTML and recommends sanitizing supplied HTML and JavaScript.
Check the exact option support in the binary and wrapper you run. An application library, a packaged command, or an integration may expose different settings or fail to forward a CLI flag.
#1 Best Overall
- Convert your PDF files into Word, Excel & Co. the easy way
- Convert scanned documents thanks to our new 2022 OCR technology
- Adjustable conversion settings
- No subscription! Lifetime license!
- Compatible with Windows 11, 10, 8.1, 7 - Internet connection required
Allow one asset folder from the command line
For a CLI workflow whose HTML refers to files under /srv/report/assets, allow that folder while retaining the restrictive policy:
wkhtmltopdf --disable-local-file-access --allow /srv/report/assets /srv/report/report.html /srv/report/report.pdfReplace the example paths with paths that exist from the renderer’s point of view. If the page uses assets in more than one directory, add an --allow option for each required location. Do not assume that a path on your laptop is the same path inside a container, function, or application worker.
If you are diagnosing a trusted, controlled document and need to determine whether local-file blocking is the cause, the broader alternative is:
wkhtmltopdf --enable-local-file-access /srv/report/report.html /srv/report/report.pdfUse this as a deliberate policy choice, not as a default workaround for arbitrary input. A global permission can expose files accessible to the renderer if hostile content is processed.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Rank #2
![Doxillion Free Document Converter – Converts DOCX, DOC, PDF, WPS and Many More Files Quickly [Download]](https://m.media-amazon.com/images/I/81tjL48MwxL.png._SL160_.png)
- Convert over 50 document file formats.
- Preview your files from Doxillion before converting them.
- Use batch conversion to convert thousands of files at once.
- Enjoy an easy-to-use, intuitive interface with a Drag and Drop file option.
- Burn your converted or original files directly to disc.
When the HTML uses relative paths
Relative references depend on how the input is supplied and how the invoking wrapper resolves it. A reference such as assets/logo.png may work in one invocation and fail in another if the input’s base location differs. Confirm the input mode and the resolved location rather than applying a single relative-path fix to every integration. When practical, use an explicit file URL or a stable absolute path appropriate to the runtime, then permit the containing directory.
Check library settings separately from CLI flags
If a web application calls libwkhtmltox or a language wrapper rather than launching the CLI directly, a command-line example may not control the renderer. The library API documents separate settings for web-image loading, user stylesheets, local-file blocking, and how loading errors are handled. Find out which API settings your wrapper actually applies, and check whether wrapper defaults override application expectations.
In particular, verify that images are enabled when images are missing, that the user stylesheet path is valid if one is configured, and that the local-file blocking setting matches the intended policy. For diagnosis, choose strict load-error handling where supported so failed resource loads are not silently hidden. The documented error policies for relevant load paths include abort, ignore, and skip; the exact setting depends on the CLI or library path being used.
Troubleshoot missing CSS, images, and fonts
- Identify the executable and version. Check the exact binary invoked by the process producing the PDF, not just the one found in an interactive shell. Record the wrapper, package, and runtime as well as the version.
- Confirm the reference and file location. Inspect the HTML’s
hrefandsrcvalues, then verify that each referenced file exists where the renderer runs. Check case, spelling, directory structure, and the base path used for relative references. - Confirm process permissions. The renderer’s user must be able to read the file and traverse its parent directories. A file allowed by wkhtmltopdf is still unavailable if the operating-system account, container mount, or sandbox denies access.
- Check the effective local-file policy. For the CLI, use
--allowfor the required directory under the documented restrictive policy. If using a wrapper or library, verify that its corresponding setting is configured and not overridden. - Check resource-specific settings. Confirm image loading is enabled, user stylesheet settings point to a readable file, and the wrapper has not disabled or altered resource handling.
- Expose load failures. Review conversion output and use strict error handling during diagnosis where available. An ignored or skipped load error can produce a PDF that looks complete but is missing styling or media.
- Reproduce inside the deployment runtime. Run the checks from the same container, serverless function, or worker environment, with the same account and environment variables as the production conversion.
“Blocked access to file”
This usually points to the local-file policy. If the document is trusted and the resource is expected, allow only its containing directory with --allow or the equivalent library setting. Then confirm that the allowed path is the path visible inside the renderer’s runtime. Do not resolve the message by globally enabling access when the HTML could be untrusted.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
- EDIT text, images & designs in PDF documents. ORGANIZE PDFs. Convert PDFs to Word, Excel & ePub.
- READ and Comment PDFs – Intuitive reading modes & document commenting and mark up.
- CREATE, COMBINE, SCAN and COMPRESS PDFs
- FILL forms & Digitally Sign PDFs. PROTECT and Encrypt PDFs
- 1 Year License for 1 Windows & 2 Mobile (Android and/or iOS) devices.
CSS loads but images or fonts do not
Different resources can have different references and runtime dependencies. Check each image and font URL independently, including whether a stylesheet itself resolves its relative url(...) references as expected. Verify file readability and image-loading settings. Font rendering can also depend on system font infrastructure, not just the presence of a font file in the application directory.
Everything works locally but fails in production
Compare the actual executable, process user, filesystem layout, libraries, fonts, environment variables, and wrapper settings. Containers and serverless functions often have a smaller filesystem and different system dependencies than a developer workstation. A path that exists on the host may not be mounted or packaged into the conversion environment.
Deploying in containers and serverless runtimes
The project’s downloads guidance identifies 0.12.6 as the stable series listed on its downloads page and gives June 11, 2020 as its release date. That is dated release metadata, not a guarantee about the package installed in a distribution or an application’s bundled copy. Confirm the version and provenance of the binary actually used.
The project also notes that builds described as static still depend on system packages, and that library versions, OpenSSL, libc, and font setup vary across distributions. It specifically calls out fontconfig and freetype2 as runtime concerns. A successful conversion of plain text therefore does not prove that CSS, images, or fonts are correctly packaged.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Rank #4
- Perfect Adobe Acrobat Pro alternative – lifetime license for Windows 10 and 11.
- EDIT text, images, pages, hyperlinks, designs in PDF documents. ORGANIZE PDFs.
- READ and Comment on PDFs – Intuitive reading modes & document commenting and mark up tools!
- CREATE, COMBINE, SCAN and COMPRESS PDFs.
- FILL forms & Digitally Sign PDFs. Work with Digital certificates
For AWS Lambda, the project deployment example bundles dependencies and sets FONTCONFIG_PATH=/opt/fonts. Treat that as an example of a runtime-specific font configuration: use it only when it matches your package layout, and verify the configured directory and fonts from within the function environment.
Deployment checklist
- Package the same wkhtmltopdf binary and required libraries used by the deployed application.
- Include the local asset directories in the image or function bundle and verify their runtime paths.
- Set font-related environment variables to locations that exist in that package.
- Run a representative conversion inside the deployed environment and inspect resource-load errors.
- Use the same narrow local-file allow-list in production as in the tested invocation.
Local-file access is not a security sandbox
The project advises: “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!” This is project guidance on its downloads and status pages, not an independent security test.
The project’s AppArmor guidance explains that the CLI restriction can be bypassed if an attacker exploits a vulnerability in a prebuilt binary. It describes AppArmor as a way to limit file access to approved locations and restrict process capabilities, and says the sample profile must be customized for the application’s work paths. Red Hat systems use SELinux rather than AppArmor, so use the host’s appropriate confinement mechanism. A CLI allow-list is useful least-privilege configuration, but should not be the only boundary for hostile content.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.When to keep wkhtmltopdf—and when to reassess
If your existing reports render correctly with a known binary, controlled HTML, packaged assets, and a constrained runtime, correcting the allow-list and deployment paths may be sufficient. If the real problem is an old or difficult-to-maintain renderer, compare alternatives on the needs that matter: the security boundary and local-resource defaults, required HTML/CSS and JavaScript compatibility, operating-system dependencies, predictable asset packaging, and maintenance and security-update posture.
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 matchBest Value
![Doxillion Free Document Converter for Mac – Converts DOCX, DOC, PDF, WPS and Many More Files Quickly [Download]](https://m.media-amazon.com/images/I/51Xjwhv3w2L._SL160_.jpg)
- Convert over 50 document file formats.
- Preview your files from Doxillion before converting them.
- Use batch conversion to convert thousands of files at once.
- Enjoy an easy-to-use, intuitive interface with a Drag and Drop file option.
- Burn your converted or original files directly to disc.
The project status guidance discusses wkhtmltopdf’s older Qt/WebKit foundation and suggests considering alternatives for controlled report generation or dynamic JavaScript-heavy pages. That is a reason to evaluate fit, not evidence that every alternative will render an existing report identically. Test representative pages and fonts in the target runtime before switching.
Or skip the browser setup
If the goal is to capture a webpage rather than render your own local HTML assets through wkhtmltopdf, ScreenshotNeo is a website screenshot API and MCP server. Its API can return a screenshot or PDF; it is not a way to grant wkhtmltopdf access to local files. One GET request can capture a URL:
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 request options. ScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses include X-Page-Verdict and X-Billed headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients.
The free plan includes 1,000 screenshots per month with no card required; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month—no card required.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsFrequently Asked Questions
Does allowing a folder with --allow make wkhtmltopdf safe for untrusted HTML?
No. The project warns against rendering untrusted HTML and recommends OS-level confinement as an additional control; a CLI option is not a complete security boundary.
Why does the same command work in a terminal but not from my application?
The application may invoke a different binary, user, wrapper, environment, or filesystem view. Identify and test the actual conversion process and runtime.
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.
