wkhtmlapp

Bindings to wkhtmltopdf and wkhtmltoimage

wkhtmlapp depends on the wkhtmltopdf application to generate PDFs or images, abstracted in such a way that it can support multithreading without damaging the main instance. This library was developed inspired by barryvdh's laravel-snappy.

Resource	Link
Crate
Documentation	docs.rs/wkhtmlapp
Upstream	wkhtmltopdf.org
Wkhtmltox Version	wkhtmltox-0.12.6-1

⚠️ Upstream status: the wkhtmltopdf project is archived and unmaintained since 2023. It still works well for server-side rendering, but no new releases or security fixes are expected. Also note that since wkhtmltox 0.12.6, local file access is disabled by default — pass enable-local-file-access if your HTML references local assets.

Required setup before use

• Set wkhtmltopdf in your system PATH, or download the portable versions of wkhtmltopdf for your operating system and reference them via environment variables.
• Note: Since v1.1.0, this library no longer loads .env files automatically. If you need .env support, load it in your application (e.g., using dotenvy or dotenv). See .env.example for the supported variables.

Environment variables:

   WKHTMLAPP_WORK_DIR="storage/temp"
   WKHTMLTOPDF_CMD="assets/bin/wkhtmltopdf/0.16/wkhtmltopdf"
   WKHTMLTOIMG_CMD="assets/bin/wkhtmltopdf/0.16/wkhtmltoimage"

ONLY SOME ARGUMENTS HAVE BEEN VERIFIED, USE WITH CAUTION

Features

• Convert html code to PDF and IMG
• Convert html file to PDF and IMG
• Convert url link to PDF and IMG
• Repeatable options (cookie, custom-header, allow, ...) via add_arg()
• cover / toc objects with correct positional placement
• Work dir housekeeping via clear_work_dir()

Notes on behavior

• Output naming: every render writes to the work dir as <uuid>-<name>.<ext>, so concurrent renders never collide. The name must be a plain file name — names containing /, \ or .. are rejected to prevent writing outside the work dir.
• Output cleanup: rendered files are never deleted automatically. Call pdf_app.clear_work_dir() / img_app.clear_work_dir() periodically (it removes files only, not subdirectories), or manage the files yourself. Partial outputs of failed renders are removed automatically.
• Two-value options (cookie, custom-header, post, post-file, replace) take both values separated by a space: set_arg("cookie", "session abc123") becomes --cookie session abc123.
• Flags use "true" / "false" string values: "true" emits the flag, "false" omits it.
• Logging: diagnostics go through the log facade. Enable them from your application with e.g. env_logger and RUST_LOG=debug.

Change Logs

1.2.0

• Fix: cover object no longer drops its input: set_arg("cover", "cover.html") now correctly emits cover cover.html as a positional object. Previously the input value was silently discarded, making cover pages impossible to use.
• Fix: deterministic argument order: options are emitted sorted (they came from a HashMap in random order), and cover/toc are placed as positional objects with TOC options after the toc object, as wkhtmltopdf requires.
• Fix: render errors always include wkhtmltox's stderr: stderr is now captured in every mode. Previously, with debug enabled, failures were reported with an empty error message.
• Fix: binary check no longer pollutes stdout: PdfApp::new()/ImgApp::new() verified the binary with an inherited stdout, printing the wkhtmltox version banner to the host application's console. The check is now silent and the "not found" error names the actual binary (before it always said wkhtmltopdf, even for wkhtmltoimage).
• Security: output names are validated: names containing /, \ or .. are rejected, preventing path traversal outside the work dir when names come from user input.
• New: add_arg() for repeatable options: cookie, custom-header, allow, run-script, etc. can now be passed multiple times. Two-value options (--cookie name value) are supported via space-separated values.
• New: clear_work_dir(): removes leftover output files from the work dir (files only, never subdirectories). Outputs are never deleted automatically — this makes cleanup explicit.
• New: partial outputs of failed renders are removed instead of accumulating in the work dir.
• Removed APP_DEBUG env var: debug behavior was inconsistent (runtime env var vs. compile-time debug_assertions). All diagnostics now go through the log facade — control them with RUST_LOG in the consuming application.
• Internal: the three run_with_* paths were unified into a single execute() helper (~90 fewer duplicated lines), and default_work_dir() no longer can panic on non-UTF8 paths.
• Quality: crate-level and API documentation, unit tests for argument building and name validation, integration tests marked #[ignore] (run with cargo test -- --include-ignored), GitHub Actions CI (fmt + clippy + tests), rust-version = "1.80" and docs.rs metadata in Cargo.toml, .env replaced by .env.example.

1.1.0

• WkhtmlError implements std::error::Error: Now compatible with ? operator, anyhow, thiserror and the standard Rust error ecosystem.
• Removed dotenv dependency: The library no longer forces .env loading. This is now responsibility of the consuming application. Reduces coupling and dependency footprint.
• run() returns PathBuf instead of String: Output file paths are now returned as std::path::PathBuf, which is more idiomatic for file system operations in Rust.
• HashSet for option validation: Replaced Vec linear search with HashSet using LazyLock for O(1) lookups. Improves validation performance with 140+ options.
• Default for ImgFormat: ImgFormat now implements Default (defaults to Jpg).
• Deduplicated build_args logic: The argument building logic was duplicated in PdfApp and ImgApp. Now consolidated into Core::build_args().
• Updated dependencies: log to 0.4, uuid to 1 (removed unused serde feature), env_logger to 0.11.

1.0.0

• Successfully tested with actix-web on windows and linux systems

0.2.0

• You can instantiate PdfApp or ImgApp which will only serve to generate pdf's or images respectively or instantiate App which gives you access to both

0.1.5

• Arg value is no longer optional

0.1.4

• Lifetime was implemented, allowing to use str instead of String in sending arguments

0.1.3

• Fix: Return full file path

Example

use wkhtmlapp::WkhtmlError;
fn main() -> Result<(), WkhtmlError> {
    let mut app = wkhtmlapp::App::new()?;
    let app_report = app.pdf_app
        .set_arg("enable-smart-shrinking", "true")?
        .set_arg("title", "Torres")?
        .set_arg("header-right", "Página [page] de [toPage]")?
        .set_arg("margin-top", "18")?;

    // run() returns a PathBuf with the generated file path
    let report = app_report.run(
        wkhtmlapp::WkhtmlInput::Url("https://www.w3schools.com/graphics/svg_intro.asp"),
        "demo",
    )?;
    println!("report: {:?}", report);
    Ok(())
}

PDF Examples

let pdf_app = PdfApp::new().expect("Failed to init PDF Application");
let html_code = r#"<html><body><div>DEMO</div></body></html>"#;
// All run() calls return std::path::PathBuf
let file_path = pdf_app.run(WkhtmlInput::Html(html_code),"demo")?;
let file_path = pdf_app.run(WkhtmlInput::File("examples/index.html"), "demo")?;
let file_path = pdf_app.run(
            WkhtmlInput::Url("https://www.rust-lang.org/en-US/"),
            "demo",
        )?;

Cover page, TOC and repeatable options

let mut pdf_app = PdfApp::new()?;
pdf_app
    .set_arg("cover", "cover.html")?          // positional object: cover cover.html
    .set_arg("toc", "true")?                  // positional object: toc
    .set_arg("toc-depth", "2")?               // emitted after the toc object
    .add_arg("cookie", "session abc123")?     // --cookie session abc123
    .add_arg("cookie", "theme dark")?         // repeatable: a second --cookie
    .add_arg("allow", "/var/www/assets")?;

let report = pdf_app.run(WkhtmlInput::File("report.html"), "report")?;

// Outputs are never deleted automatically; clean up when appropriate:
pdf_app.clear_work_dir()?;

IMG Examples

let mut image_app = ImgApp::new().expect("Failed to init image Application");
let args = HashMap::from([("height", "20"), ("width", "20")]);

let res = image_app
    .set_format(ImgFormat::Png)?
    .set_args(args)?
    .run(WkhtmlInput::File("examples/index.html"), "demo")?;

ImgApp Args

PdfApp Args

License

MIT

Free Software, Hell Yeah!