wkhtmltoimage 0.10.0 rc2 Manual

This file documents wkhtmltoimage, a program capable of converting HTML documents into images.

Contact

If you experience bugs or want to request new features please visit http://code.google.com/p/wkhtmltopdf/issues/list, if you have any problems or comments please feel free to contact me: uuf6429@gmail.com

License

Copyright (C) 2010 wkhtmltopdf/wkhtmltoimage Authors.

License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

Authors

Written by Jan Habermann, Christian Sciberras and Jakob Truelsen. Patches by Mehdi Abbad, Lyes Amazouz, Pascal Bach, Emmanuel Bouthenot, Benoit Garret and Mário Silva.

Synopsis

wkhtmltoimage [OPTIONS]... <input file> <output file>

General Options

--allow<path> Allow the file or files from the specified folder to be loaded (repeatable)
--checkbox-checked-svg<path> Use this SVG file when rendering checked checkboxes
--checkbox-svg<path> Use this SVG file when rendering unchecked checkboxes
--cookie<name> <value> Set an additional cookie (repeatable)
--cookie-jar<path> Read and write cookies from and to the supplied cookie jar file
--crop-h<int> Set height for croping
--crop-w<int> Set width for croping
--crop-x<int> Set x coordinate for croping
--crop-y<int> Set y coordinate for croping
--custom-header<name> <value> Set an additional HTTP header (repeatable)
--custom-header-propagationAdd HTTP headers specified by --custom-header for each resource request.
--no-custom-header-propagationDo not add HTTP headers specified by --custom-header for each resource request.
--debug-javascriptShow javascript debugging output
--no-debug-javascriptDo not show javascript debugging output (default)
--encoding<encoding> Set the default text encoding, for input
-H,--extended-helpDisplay more extensive help, detailing less common command switches
-f,--format<format> Output file format (default is jpg)
--height<int> Set screen height (default is calculated from page content) (default 0)
-h,--helpDisplay help
--htmldocOutput program html help
--imagesDo load or print images (default)
--no-imagesDo not load or print images
-n,--disable-javascriptDo not allow web pages to run javascript
--enable-javascriptDo allow web pages to run javascript (default)
--javascript-delay<msec> Wait some milliseconds for javascript finish (default 200)
--load-error-handling<handler> Specify how to handle pages that fail to load: abort, ignore or skip (default abort)
--disable-local-file-accessDo not allowed conversion of a local file to read in other local files, unless explecitily allowed with --allow
--enable-local-file-accessAllowed conversion of a local file to read in other local files. (default)
--manpageOutput program man page
--minimum-font-size<int> Minimum font size
--password<password> HTTP Authentication password
--disable-pluginsDisable installed plugins (default)
--enable-pluginsEnable installed plugins (plugins will likely not work)
--post<name> <value> Add an additional post field (repeatable)
--post-file<name> <path> Post an additional file (repeatable)
-p,--proxy<proxy> Use a proxy
--quality<int> Output image quality (between 0 and 100) (default 94)
--radiobutton-checked-svg<path> Use this SVG file when rendering checked radiobuttons
--radiobutton-svg<path> Use this SVG file when rendering unchecked radiobuttons
--readmeOutput program readme
--run-script<js> Run this additional javascript after the page is done loading (repeatable)
-0,--disable-smart-width*Use the specified width even if it is not large enough for the content
--stop-slow-scriptsStop slow running javascripts (default)
--no-stop-slow-scriptsDo not Stop slow running javascripts (default)
--transparent*Make the background transparent in pngs
--user-style-sheet<url> Specify a user style sheet, to load with every page
--username<username> HTTP Authentication username
-V,--versionOutput version information an exit
--width<int> Set screen width (default is 1024) (default 1024)
--window-status<windowStatus> Wait until window.status is equal to this string before rendering page
--zoom<float> Use this zoom factor (default 1)

Items marked * are only available using patched QT.

Specifying A Proxy

By default proxy information will be read from the environment variables: proxy, all_proxy and http_proxy, proxy options can also by specified with the -p switch

<type> := "http://" | "socks5://"
<serif> := <username> (":" <password>)? "@"
<proxy> := "None" | <type>? <sering>? <host> (":" <port>)?

Here are some examples (In case you are unfamiliar with the BNF):

http://user:password@myproxyserver:8080
socks5://myproxyserver
None

Static version

On the wkhtmltopdf website you can download a static version of wkhtmltopdf http://code.google.com/p/wkhtmltopdf/downloads/list. This static binary will work on most systems and comes with a build in patched QT.

Unfortunately the static binary is not particularly static, on Linux it depends on both glibc and openssl, furthermore you will need to have an xserver installed but not necessary running. You will need to have different fonts install including xfonts-scalable (Type1), and msttcorefonts. See http://code.google.com/p/wkhtmltopdf/wiki/static for trouble shouting.

Compilation

It can happen that the static binary does not work for your system for one reason or the other, in that case you might need to compile wkhtmltoimage yourself.

Installation

There are several ways to install wkhtmltoimage. You can download a already compiled binary, or you can compile wkhtmltoimage yourself.

Examples

This section presents a number of examples of how to invoke wkhtmltoimage.

To convert a remote HTML file to PNG:

wkhtmltoimage http://www.google.com google.png

To convert a local HTML file to PNG:

wkhtmltoimage my.html my.png