wkhtmltopdf Does Not Load Local CSS or Images: Fixes

If wkhtmltopdf omits local CSS or images, first check whether local-file access is allowed, whether image loading is enabled, and whether the referenced files exist where the conversion process can read them. In wkhtmltopdf 0.12.6, local-file access is disabled by default; use --enable-local-file-access for broad access or repeatable --allow <path> entries to permit specific directories. Images load by default unless disabled with --no-images. [wkhtmltopdf usage documentation]

1. Identify the input and the exact conversion

Before changing flags, establish what wkhtmltopdf is converting and how it is invoked. A local HTML file, standard input, and a remote URL can have different resource locations and access requirements. Record the exact binary version and, if applicable, the language wrapper or library.

wkhtmltopdf --version
wkhtmltopdf --extended-help

The usage reference cited here documents version 0.12.6. Do not assume a packaged binary or wrapper has identical defaults. Compare the same input with the same executable and options that the failing job uses.

2. Allow access to local files

When local HTML references local stylesheets or images, the converter needs permission to read those files. The documented default is to disable local-file access. Choose the narrowest access rule that fits the job.

Allow all local files for this conversion

wkhtmltopdf --enable-local-file-access input.html output.pdf

Allow only the asset directories needed

Use --allow once for each directory the document needs to read. The option is repeatable:

wkhtmltopdf \
  --allow /path/to/site/css \
  --allow /path/to/site/images \
  input.html output.pdf

Replace the example paths with directories that exist in the environment running the conversion. Folder-scoped access is useful when the job should not read arbitrary local files. The option reference describes --allow <path> as allowing files from a specified folder. [wkhtmltopdf usage documentation]

Check explicit blocking settings

--disable-local-file-access is documented as the default. If your invocation includes it, local resources remain blocked unless their folders are explicitly allowed. Look for conflicting or duplicated flags in shell scripts, deployment configuration, and wrapper defaults.

3. Confirm that images are enabled

Images are enabled by default in the documented CLI, but --no-images turns image loading off. Remove that option or explicitly pass --images when appropriate:

wkhtmltopdf --images --enable-local-file-access input.html output.pdf

For library integrations, inspect the effective web.loadImages setting as well as the local-file policy. A correct CLI command does not prove that a wrapper passes the same settings to the page being converted. [wkhtmltopdf library page settings]

4. Verify every referenced asset path

Permission cannot fix a path that points to the wrong location. Check each stylesheet and image reference and confirm the conversion process can see the target file:

Confirm the file exists in the conversion runtime, container, or host, not only on a developer’s machine.
Check spelling, capitalization, directory names, and file permissions.
Compare the reference in the HTML or CSS with the location of the input document and the actual asset location.
Check assets referenced from within CSS as well as assets referenced directly by HTML.
If the job runs under a service account or inside a container, inspect paths and permissions from that same environment.

Path resolution can depend on input mode, wrapper behavior, operating system, and how the document is supplied. Do not assume one path spelling or resolution rule works for every setup.

5. Check print media and media-load errors

--print-media-type selects print styles instead of screen styles. If assets disappear only when this option is enabled, compare the output with and without it and inspect the applicable print CSS rules. A report for wkhtmltopdf 0.12.6 on macOS 12.6.1 described images returning after this option was removed; that is an environment-specific report, not proof of a general rendering defect. [wkhtmltopdf issue report]

Also inspect load-error handling. The documented CLI default for --load-media-error-handling is ignore, so a missing stylesheet or image may not stop PDF generation. The library exposes load.loadErrorHandling and load.printMediaType. [wkhtmltopdf usage documentation, library page settings]

6. Diagnose wrapper and library settings

When a shell command works but an application does not, compare the effective options that reach the conversion process. Inspect the page or object settings, not only global application configuration. Relevant library settings include:

web.loadImages — whether images are loaded.
load.blockLocalFileAccess — whether local-file access is blocked.
load.loadErrorHandling — how loading errors are handled.
load.printMediaType — whether print media is selected.

For example, a Go wrapper issue documented a local stylesheet blocked in a wrapper context. It is a useful reminder to check wrapper-level behavior, but does not establish how every binding handles settings. [Go wrapper issue report]

7. A minimal troubleshooting sequence

Run wkhtmltopdf --version and record the exact command or wrapper and its input mode.
Check whether local access is blocked. Test with --enable-local-file-access, or use repeatable --allow entries for the required asset folders.
Confirm --no-images is absent and, for a library, that web.loadImages is enabled.
Verify every file exists and is readable from the conversion runtime; check CSS-linked assets too.
Compare screen and print behavior by toggling --print-media-type and reviewing print CSS.
Inspect warnings and load-error settings. Missing media can be ignored while the PDF is still produced.
If only the application or wrapper fails, inspect the actual page/object options and arguments passed to wkhtmltopdf.

8. Common errors and fixes

Symptom	Likely cause	What to check or change
“Blocked access to file” or local resources are missing	Local-file access is disabled	Try `--enable-local-file-access`, or allow only needed folders with repeatable `--allow` options.
Images are all missing	`--no-images` or a disabled library setting	Remove `--no-images`; inspect `web.loadImages`.
Only some images or stylesheets are missing	Incorrect path, unreadable file, or a CSS asset reference that points elsewhere	Verify each target from the converter’s runtime and check file permissions.
Command-line output works, application output does not	Wrapper or per-page settings differ	Inspect effective object/page options and the invocation the wrapper produces.
Assets disappear with print mode	Print CSS or print-specific loading behavior	Compare with and without `--print-media-type`; inspect print rules. Treat issue reports as leads, not universal explanations.
PDF succeeds despite missing assets	Media load errors are ignored	Review `--load-media-error-handling` or the library’s `load.loadErrorHandling` and inspect warnings.
Enabling local access did not fix the problem	Wrong path, permissions, input mode, wrapper behavior, or another setting	Trace the exact requested file and effective options. A Windows issue report, for example, describes local image errors despite the flag; it is one case, not a universal behavior. [issue report]

9. Reliability, performance, and cost notes

Allowing local access changes which files a conversion can read; use folder-scoped --allow rules when broad access is unnecessary. Neither the cited usage reference nor the issue reports provide performance benchmarks or success rates for these fixes. If the PDF is missing assets, a successful process exit alone may not be enough: check output content and conversion warnings because media errors can be ignored. Cost depends on how wkhtmltopdf is deployed and operated; the research sources do not establish a universal price or cost comparison.

10. Or skip the browser setup

If you need a website screenshot or PDF without managing a local browser capture setup, ScreenshotNeo provides a screenshot API and MCP server. For a screenshot, one GET request returns an image; 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}`);

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each step can be turned off.
Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and billing status.
An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.
The free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots.

Frequently asked questions

Does `--enable-local-file-access` allow every local file?

It permits a local input to read other local files. If the conversion should be limited to particular folders, use repeatable --allow <path> entries instead.

Does wkhtmltopdf disable images by default?

The cited 0.12.6 CLI reference says images load by default. Check for --no-images and wrapper settings if they do not appear.

Why does the PDF still get created when assets fail?

The documented media-load error handling default is to ignore errors, so conversion can continue even when a stylesheet or image fails to load.

Will these options work the same in every wrapper?

Not necessarily. Verify the effective page or object settings and the arguments passed by the exact wrapper and build in use.