imgkit

1.2.3 · active · verified Sat Apr 11

imgkit is a Python 2 and 3 wrapper for the `wkhtmltoimage` utility, which converts HTML content into various image formats (JPG, PNG, etc.) using the Webkit rendering engine and Qt. The library currently stands at version 1.2.3 and is actively maintained, though releases occur on an irregular cadence, with the last major update in February 2023.

Warnings

gotcha The most common issue is `IOError: 'No wkhtmltoimage executable found'`. imgkit is a wrapper and requires the external `wkhtmltoimage` binary (part of `wkhtmltopdf`) to be installed on your system and accessible in the system's PATH, or its path explicitly configured.
Fix: Install `wkhtmltopdf` for your operating system. On Linux/macOS, ensure the `wkhtmltoimage` binary is in your `$PATH`. On Windows, ensure `wkhtmltoimage.exe` (including the `.exe` extension) is in your PATH or explicitly set via `imgkit.config(wkhtmltoimage='C:\path\to\wkhtmltoimage.exe')`.
gotcha On Debian/Ubuntu, the `wkhtmltopdf` package from official repositories often has reduced functionality (e.g., missing QT patches). This can lead to issues with outlines, headers, footers, or TOC.
Fix: Instead of `apt-get install wkhtmltopdf`, download and install the static binary from the official wkhtmltopdf site (`https://wkhtmltopdf.org/downloads.html`) or use a script that fetches a full-featured version.
gotcha If using the `xvfb` option in imgkit (e.g., for headless environments), you might encounter `IOError: 'No xvfb executable found'`.
Fix: Install `xvfb` (e.g., `sudo apt-get install xvfb` on Debian/Ubuntu) and ensure `xvfb-run` is in your system's PATH or explicitly configured in imgkit.
gotcha A generic `IOError: 'Command Failed'` indicates that `wkhtmltoimage` was invoked but exited with a non-zero status, meaning it couldn't process the input for various reasons (e.g., invalid HTML, resource loading issues, out of memory).
Fix: Check the input HTML for errors. Run `wkhtmltoimage` directly from the command line with your input to see its specific error messages. Increase verbosity if possible or check system logs.

Install

pip install imgkit Install Python package
sudo apt-get install wkhtmltopdf Install wkhtmltopdf (Debian/Ubuntu - see warnings)
brew install --cask wkhtmltopdf Install wkhtmltopdf (macOS)
Download installer from https://wkhtmltopdf.org/downloads.html Install wkhtmltopdf (Windows/Other OS)

Imports

imgkit
```
import imgkit
```
The primary module for all functionalities.
config
```
import imgkit
config = imgkit.config(wkhtmltoimage='/path/to/wkhtmltoimage')
```
Used to explicitly set the path to the wkhtmltoimage binary or other global options.

Quickstart

This quickstart demonstrates how to convert HTML from a URL, a local file, or a direct string into an image using `imgkit`. It also includes an example of how to configure the path to the `wkhtmltoimage` executable, which is a common requirement for the library to function correctly.

import imgkit
import os

# --- Option 1: Convert from a URL ---
# imgkit.from_url takes a URL and an output filename
imgkit.from_url('http://google.com', 'google.jpg')
print('Converted Google to google.jpg')

# --- Option 2: Convert from an HTML file ---
# Create a dummy HTML file
with open('test.html', 'w') as f:
    f.write('<h1>Hello from imgkit!</h1><p>This is a test.</p>')
imgkit.from_file('test.html', 'test_output.png')
print('Converted test.html to test_output.png')

# --- Option 3: Convert from an HTML string ---
html_string = '<html><body><h2>Inline HTML</h2><p style="color: blue;">Styled content.</p></body></html>'
imgkit.from_string(html_string, 'string_output.jpeg')
print('Converted HTML string to string_output.jpeg')

# --- Option 4: Configure wkhtmltoimage path (if not in PATH) ---
# Replace with the actual path to your wkhtmltoimage executable
# Example for Windows: r'C:\Program Files\wkhtmltopdf\bin\wkhtmltoimage.exe'
# Example for Linux: '/usr/local/bin/wkhtmltoimage'
WKHTMLTOIMAGE_PATH = os.environ.get('WKHTMLTOIMAGE_BINARY_PATH', '') 

if WKHTMLTOIMAGE_PATH:
    configuration = imgkit.config(wkhtmltoimage=WKHTMLTOIMAGE_PATH)
    imgkit.from_string('<h1>Configured Path Test</h1>', 'path_config_output.jpg', config=configuration)
    print('Converted with custom wkhtmltoimage path.')
else:
    print('WKHTMLTOIMAGE_BINARY_PATH environment variable not set. Skipping custom path configuration example.')

# Clean up dummy file
os.remove('test.html')

view raw JSON →