How to convert HTML to image using wkhtmltoimage and Python

Convert HTML to JPG, PNG, and other image formats 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 (JPG), 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. If you also need to convert HTML to PDF, the related wkhtmltopdf tool covers that workflow.

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 50 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 you encounter. You can also automate conversions through our Zapier HTML-to-image integration.

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 wkhtmltoimage 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. Create a new directory with a file called main.py. This file will contain the conversion code.
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 format is determined by the file extension — use .jpg for JPEG, .png for PNG, or .bmp for bitmap. The subprocess.run(opens in a new tab) function returns a CompletedProcess object. Check result.returncode to confirm the conversion succeeded (0 means success), or pass check=True to raise a CalledProcessError automatically on non-zero exit status.

Customizing the output

Customize the output by passing additional options to the wkhtmltoimage command. You can specify width, height, quality, and cropping:

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

This sets the image to 800 pixels wide and 600 pixels tall.

The -q option runs the command in quiet mode, suppressing console 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().

See the full list of options(opens in a new tab) for additional flags.

Converting HTML to JPG format

To produce a JPG (JPEG) file instead of PNG, change the output file extension and use the --quality flag to control compression. JPG is a good choice when you need smaller file sizes and don’t require transparency:

subprocess.run(["wkhtmltoimage", "--format", "jpg", "--quality", "85", "input.html", "output.jpg"])

The --quality flag accepts values from 0 to 100, where higher values produce better quality at the cost of larger file sizes. A value between 80 and 90 typically offers a good balance. For converting other document types to images, see our guide on converting PDF to JPG with Python.

Alternatives to wkhtmltoimage

wkhtmltoimage isn’t the only tool for HTML-to-image conversion. Here’s how common alternatives compare:

For projects that need modern CSS and JavaScript rendering, consider migrating from Puppeteer to Playwright. For production-scale conversion, the Nutrient HTML-to-image API eliminates the need to manage browser dependencies.

Common issues and troubleshooting

Common problems during HTML-to-JPG and HTML-to-image conversion:

• Blank or white output — The HTML page may rely on JavaScript to render content. wkhtmltoimage has limited JavaScript support, so add --javascript-delay 2000 to wait for scripts to execute, or consider a Chromium-based tool like Puppeteer.
• Missing fonts or broken layout — Install the required fonts on the server. On Linux, install fontconfig and common font packages. Use --encoding utf-8 if special characters appear garbled.
• “Cannot connect to X server” on Linux — wkhtmltoimage requires a display server. Install xvfb and run with xvfb-run wkhtmltoimage input.html output.jpg.
• Low-quality JPG output — Set --quality 90 or higher. The default quality can produce visible compression artifacts, especially for text-heavy pages.
• CSS not loading from external stylesheets — Use --enable-local-file-access when converting local HTML files, or inline your CSS to avoid path resolution issues.
• Large file sizes — For JPG, reduce --quality to 70–80. For PNG, reduce --width or use a tool that supports WebP output for better compression.

For recurring conversion tasks or automated reporting, refer to our guides on generating images from text and Zapier HTML-to-image automation.

Conclusion

wkhtmltoimage handles basic HTML-to-image conversion well for static pages. For related document conversion workflows, check out how to convert HTML to PDF using wkhtmltopdf and Python or explore the top HTML-to-PDF conversion tools.

For a commercially supported alternative, Nutrient offers an HTML-to-image API that can be integrated into your workflow or application. You can also use it alongside our HTML-to-PDF conversion tools in JavaScript and other languages. Create an account to unlock 50 free credits per month.

FAQ

Related

HTML-to-image conversion: Convert HTML to image with wkhtmltoimage and Laravel, Zapier HTML-to-image automation, creating images from text on the web

HTML-to-PDF conversion: HTML to PDF with wkhtmltopdf and Python, top HTML-to-PDF conversion tools, HTML to PDF in JavaScript, HTML to PDF using html2pdf.js, generate PDF reports from HTML in Python

Image and document conversion: Convert PDF to JPG using Python, convert DOCX to WebP in Python

Browser automation: Migrating from Puppeteer to Playwright