How to Convert HTML to Image Using wkhtmltoimage and Python

In this tutorial, you’ll learn how to use wkhtmltoimage and Python to convert HTML to PNG, which is a common task in web development. Various use cases include creating screenshots of web pages; social media sharing; and creating email signatures, reports, and documentation. One tool that can be used for this task is wkhtmltoimage, a command-line utility that’s capable of converting HTML to various image formats, including PNG, JPEG, BMP, and TIFF.

wkhtmltoimage uses the WebKit rendering engine to convert HTML to images, which means the resulting images will look similar to what you see in a web browser. It also allows you to specify various options, such as image size and quality, to customize the output.

Development Considerations

Before starting, it’s important to note that wkhtmltoimage is a command-line tool and doesn’t have a built-in graphical user interface (GUI). It’s also an open source tool — created in 2008 by Jakob Truelsen — and it isn’t being consistently maintained at this time.

If you’re considering a commercial solution, PSPDFKit offers an HTML to Image API in Python. Our hosted solution gives you 100 free image conversions per month, and for larger amounts, 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

The first step in using wkhtmltoimage is to install it on your system. The installation process will vary depending on your operating system, but for Windows and macOS, you can download the appropriate binary from the project’s website.

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 module to run the command and capture the output. The subprocess module allows 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.pdf. It’s important to note that the output file format is determined by the file extension — in this case, .png. The subprocess.run 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 are used to set the quality and crop size of the output image.

The input parameter of subprocess.run() expects a byte-like object. This is why you converted the input string to bytes using the bytes() function or the encode() method.

Both the encode() and bytes() functions convert a string to bytes, but the encode() method is used to convert a string to bytes using a specific encoding, whereas the bytes() function takes in the encoding as an additional argument.

You can experiment with different options and see how they affect the resulting image.

Conclusion

In this post, you learned how to use the wkhtmltoimage library in combination with Python to convert an HTML file to a PNG. The post also discussed how to pass additional options to the command to customize the output. You can use this method to automate the conversion of HTML documents to PNG in your web development project. You can also check out our post on how to convert HTML to PDF using wkhtmltopdf and Python.

If you’re looking to add more robust PDF capabilities, PSPDFKit offers a commercial option that gives you 100 free conversions per month. Our HTML-to-Image API can easily be integrated into your workflow or application. Create an account to unlock 100 free conversions per month.

FAQ

What is wkhtmltoimage?

wkhtmltoimage is a command-line tool that converts HTML to various image formats, such as PNG, JPEG, BMP, and TIFF, using the WebKit rendering engine.

How do I install wkhtmltoimage?

You can download the appropriate binary for your operating system from the official website and follow the installation instructions.

How do I use wkhtmltoimage with Python?

You can use the subprocess module in Python to call the wkhtmltoimage command and convert HTML to an image.

Can I customize the output image?

Yes, you can customize the output by specifying options such as width, height, quality, and cropping using the command-line options.

What are some common use cases for converting HTML to images?

Common use cases include creating screenshots of web pages, generating content for social media, creating email signatures, reports, and documentation.

Is there a commercial alternative to wkhtmltoimage?

Yes, PSPDFKit offers an HTML to Image API with 100 free conversions per month, providing a more robust and maintained solution.