How to convert HTML to image using wkhtmltoimage and Python

Convert HTML to images using wkhtmltoimage(opens in a new tab) and Python. This common web development task enables creating screenshots, social media graphics, email signatures, reports, and documentation. wkhtmltoimage is a command-line utility that converts HTML to PNG, JPEG, BMP, and TIFF formats using the WebKit rendering engine. The resulting images look similar to what you see in a web browser, and you can customize output with options for image size, quality, and cropping.

Development considerations

wkhtmltoimage is a command-line tool without a graphical user interface (GUI). It’s an open source tool — created in 2008 by Jakob Truelsen — and it isn’t being consistently maintained(opens in a new tab) at this time.

If you’re considering a commercial solution, Nutrient offers an HTML-to-image API in Python. Our hosted solution gives you 200 free credits, and we offer additional packages for a per-document fee. Our solutions are regularly maintained, with releases occurring multiple times throughout the year. We also offer one-on-one support to handle any issues or challenges you encounter.

Installing wkhtmltoimage

Download the appropriate binary for your operating system from the project’s website(opens in a new tab). The installation process varies by platform.

Once the download is complete, run the installer and follow the prompts to complete the installation.

• On Windows: The wkhtmltoimage executable will be located in the installation directory — by default, it’s C:\Program Files\wkhtmltoimage\bin.
• On Mac: The wkhtmltoimage executable will be located in the installation directory — by default, it’s /usr/local/bin.

You can check the path of the wkhtmltopdf executable on your system by running the command where wkhtmltoimage on Windows and which wkhtmltoimage on Mac in the command line.

Integrating wkhtmltoimage with Python

1. To start, create a new Python project. You can do this by creating a new directory and then creating a new file called main.py in that directory. This file will be the entry point into your project and will contain the code to convert your HTML file to PNG.
2. Use wkhtmltoimage in your Python script by calling the subprocess(opens in a new tab) module to run the command and capture the output. The subprocess module enables you to start new processes from within your Python script:

import subprocess

# Use subprocess to call the wkhtmltoimage command.
subprocess.run(['wkhtmltoimage', 'input.html', 'output.png'])

In the example above, the input file is input.html, and the output file is output.png. The output file format is determined by the file extension — in this case, .png. The subprocess.run(opens in a new tab) function returns the exit code of the command, which can be used to check if the conversion was successful.

Customizing the output

You can customize the output image by passing additional options to the wkhtmltoimage command. For example, you can specify the width and height of the image, the quality of the image, and whether to crop the image. Here’s an example of how to do this:

subprocess.run(["wkhtmltoimage", "--width", "800", "--height", "600", "input.html", "output.png"])

In the example above, the width and height of the image are set to 800 and 600 pixels, respectively.

You can use the -q option to run the command in quiet mode, which will suppress the output of the command. This is useful if you want to run the command in the background and don’t want to see the output:

subprocess.run(["wkhtmltoimage", "-q", "input.html", "output.png"])

• The --crop-w and --crop-h options can be used to crop the image to a specific width and height. For example, --crop-w 800 --crop-h 600 will crop the image to 800 pixels wide and 600 pixels high:

import subprocess

# Read the input file in read mode.
with open("input.html", "r") as f:
    html_data = f.read()

options = ['--quality', '100', '--crop-w', '800', '--crop-h', '600']

subprocess.run(['wkhtmltoimage'] + options + ['-', "output.png"], input=html_data.encode())
# or
subprocess.run(['wkhtmltoimage'] + options + ['-', "output.png"], input=bytes(html_data, 'utf-8'))

In the example above, the options set the quality and crop size of the output image. The input parameter of subprocess.run() expects a byte-like object, so convert the string using either encode() or bytes().

Experiment with different options(opens in a new tab) to see how they affect the resulting image.

Common issues and troubleshooting

Common problems during HTML conversion:

This approach works well for recurring conversion tasks, marketing teams generating social media graphics from templates, or automated reporting workflows. Learn more in our [Zapier HTML-to-image automation][zapier guide] article.

Conclusion

This tutorial covered using wkhtmltoimage with Python to convert HTML files to PNG images, including customization options for width, height, quality, and cropping. For automated HTML-to-image conversion in web development projects, check out how to convert HTML to PDF using wkhtmltopdf and Python.

For a more robust commercial solution, Nutrient offers an HTML-to-image API that can be integrated into your workflow or application. Create an account to unlock 200 free credits per month.

FAQ