imgkit

library1.2.3pypypi✓ verified 22d ago

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.

devops serialization

pip install imgkit

github ↗package ↗

INSTALL

IMPORT

SIG · IMGKIT

imgkit

devopspythonv1.2.3

Install

1.8s avg

Import

27ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.030s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.024s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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')

imgkit --version

Debug

Known issues

gotchaThe 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')`.

affects: All versions

gotchaOn 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.

affects: All versions on affected OS

gotchaIf 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.

affects: All versions

gotchaA 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.

affects: All versions

Errors

Common errors & fixes

OSError: No wkhtmltoimage executable found: "command not found" If this file exists please check that this process can read it. Otherwise please install wkhtmltopdf - http://wkhtmltopdf.org

The `imgkit` library is a Python wrapper for the `wkhtmltoimage` command-line utility, which needs to be installed separately and accessible in your system's PATH, or its path explicitly configured for `imgkit`.

fix

First, install `wkhtmltoimage` on your system (e.g., `sudo apt-get install wkhtmltopdf` on Debian/Ubuntu, download from `wkhtmltopdf.org` for Windows/macOS). If it's not in your system's PATH, specify the full path to the `wkhtmltoimage` executable when creating the `imgkit.Config` object: `config = imgkit.Config(wkhtmltoimage='C:\Program Files\wkhtmltopdf\bin\wkhtmltoimage.exe')` (Windows example) or `config = imgkit.Config(wkhtmltoimage='/usr/local/bin/wkhtmltoimage')` (Linux example), then pass this config to `imgkit.from_...`: `imgkit.from_string(html_content, 'output.jpg', config=config)`.

ModuleNotFoundError: No module named 'imgkit'

The `imgkit` Python package has not been installed in your current Python environment.

fix

Install the `imgkit` package using pip: `pip install imgkit`.

IOError: wkhtmltoimage reported an error:\nLoading page (1/2)\nError: Could not write to output file\nExit with code 1, due to unknown error.

The `wkhtmltoimage` utility was invoked but failed during execution, often due to issues like invalid output paths, insufficient write permissions for the output file, or problems processing the input HTML/URL.

fix

Ensure the specified output path is valid and that your Python script has write permissions to that location. Also, check the input HTML/URL for correctness; try with a simpler input first. If running on a server without a graphical display, ensure `xvfb` is installed and configured, or pass appropriate `wkhtmltoimage` options (like `--no-xvfb` if truly not needed or a display server is available).

IOError: 'No xvfb executable found'

When `imgkit` runs `wkhtmltoimage` on a headless server (without a graphical display), `wkhtmltoimage` often requires `xvfb-run` (X Virtual Framebuffer) to simulate a display environment. This error occurs if `xvfb-run` is not installed or not in the system's PATH.

fix

Install `xvfb` on your system (e.g., `sudo apt-get install xvfb` on Debian/Ubuntu). Ensure `xvfb-run` is in your system's PATH or specify its full path in the `imgkit.Config`: `config = imgkit.Config(wkhtmltoimage='/path/to/wkhtmltoimage', xvfb='/usr/bin/xvfb-run')`.

Upgrade

Version history

1.2.3latest on PyPI · released Feb 23, 2023

Audit

Dependencies

wkhtmltopdf (includes wkhtmltoimage binary)requiredCore rendering engine for HTML to image conversion. Must be installed separately as a system-level executable.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/jarrekk/imgkit ↗

packagehttps://pypi.org/project/imgkit/ ↗