html2image

library2.0.7pypypi✓ verified 85d ago

The html2image package provides a Pythonic wrapper around headless web browsers (Chrome, Chromium, Edge, Firefox) to convert URLs, HTML strings, or HTML files (with CSS) into images. It's actively maintained with frequent updates, currently at version 2.0.7, focusing on browser compatibility and feature enhancements.

http-networking devops

pip install html2image

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · HTML2IMAGE

html2image

http-networkingpythonv2.0.7

Install

2.4s avg

Import

680ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.7 · 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.920 runs

installs and imports cleanly · install 0.0s · import 0.716s · 22.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.4s · import 0.643s · 23MB

20MB installed

● package 20MB

Code

Verified usage

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

Html2Image

✓ from html2image import Html2Image

This quickstart demonstrates how to initialize `Html2Image` and use it to capture screenshots from both a URL and an HTML string. Remember that a compatible headless browser must be installed on your system for `html2image` to function.

from html2image import Html2Image import os # Ensure you have a headless browser (Chrome, Chromium, Edge, or Firefox) installed # For example, on Ubuntu: # sudo apt-get update # sudo apt-get install chromium-browser hti = Html2Image(size=(1920, 1080), browser='chrome') # Take a screenshot of a website hti.screenshot( url='https://www.python.org', save_as='python_org.png', # You can specify a custom executable path if the browser isn't in PATH # executable_path='/usr/bin/chromium-browser' ) print("Screenshot of python.org saved as python_org.png") # Take a screenshot of an HTML string html_content = """ <h1 style="color: blue;">Hello, `html2image`!</h1> <p>This is a test of string conversion.</p> """ hti.screenshot(html_str=html_content, save_as='hello_html.png') print("Screenshot of HTML string saved as hello_html.png") # Clean up generated files for demonstration # os.remove('python_org.png') # os.remove('hello_html.png')

html2image --version

Debug

Known issues

gotchaThe `html2image` library requires a compatible headless web browser (Chrome, Chromium, Edge, or Firefox) to be installed on your system. It does not automatically install one. Ensure your chosen browser is in your system's PATH, or provide its executable path via the `executable_path` parameter during initialization.

fix

Install a supported browser (e.g., `sudo apt-get install chromium-browser` on Debian/Ubuntu) or set `Html2Image(executable_path='/path/to/browser')`.

affects: All versions

breakingVersion 2.0.0 introduced significant internal structural changes and revamped how browser flags are handled. Custom browser configurations or direct manipulation of browser arguments from pre-2.0.0 versions might require updates.

fix

Review the `html2image` README and documentation for version 2.0.0+ regarding browser configuration and flags. Use the `browser_args` parameter for custom arguments.

affects: <2.0.0

breakingStarting with version 2.0.5, `html2image` defaults to using Chrome's `--headless=new` flag for improved compatibility with newer browser versions. If you encounter issues with older browser versions or specific environments, you might need to revert to the old headless mode.

fix

For versions 2.0.5 and later, try initializing with `Html2Image(force_old_headless_mode=True)` or `Html2Image(browser_args=['--headless=old'])` if `headless=new` causes problems.

affects: >=2.0.5

deprecatedVersion 2.0.3 fixed an issue where the default background color flag for Chrome/Chromium changed from '0' to '000000'. If you were relying on the '0' value, it might no longer be supported on newer Chromium versions.

fix

Update any code setting the background color flag to use '000000' instead of '0'.

affects: <2.0.3

gotchaVersion 2.0.2 was yanked from PyPI shortly after its release due to a problematic wheel file. Avoid installing or using this specific version.

fix

Always install `html2image` version 2.0.3 or later to ensure stability and avoid known issues.

affects: 2.0.2

gotchaVersion 2.0.7 introduced a new and improved Command Line Interface (CLI). Existing shell scripts or automation relying on the `html2image` command-line utility might need updates to match the new argument structure and syntax.

fix

Consult the latest `html2image` documentation or run `html2image --help` to understand the updated CLI arguments and options.

affects: >=2.0.7 (for CLI users)

Errors

Common errors & fixes

FileNotFoundError: [Errno 2] No such file or directory: 'google-chrome'

The `html2image` library requires a compatible headless web browser (Chrome, Chromium, Edge, or Firefox) to be installed and accessible in the system's PATH, or its executable path explicitly provided.

fix

Install a supported browser (e.g., `sudo apt-get install chromium-browser` on Debian/Ubuntu, or ensure Chrome/Edge is installed on Windows/macOS), or specify the browser's executable path during `Html2Image` initialization: `hti = Html2Image(executable_path='/path/to/browser/executable')`.

html2image doesn't save files

Recent updates to Chromium's headless mode (e.g., transition from 'old' to 'new' headless) can cause `html2image` to fail silently when generating screenshots, resulting in no output file being produced.

fix

For `html2image` versions 2.0.5 and later, try initializing with `Html2Image(force_old_headless_mode=True)` or `Html2Image(browser_args=['--headless=old'])` if using older browser versions that may not fully support the new headless mode, or ensure your browser is up-to-date.

AttributeError: 'str' object has no attribute 'screenshot'

This error occurs when attempting to reassign the `browser` attribute of an `Html2Image` instance directly to a string after initialization, rather than configuring the browser during the `Html2Image` object's creation.

fix

Configure the browser type by passing the `browser` argument in the `Html2Image` constructor: `hti = Html2Image(browser='edge')`. The `browser` attribute itself is an internal object and should not be directly reassigned as a string.

html2image: error while loading shared libraries: libxul.so: cannot open shared object file: No such file or directory

This is a Linux-specific error indicating that the underlying web browser (often Firefox or certain Chromium versions) used by `html2image` cannot find a necessary shared library on the system.

fix

Install the missing shared library. For `libxul.so`, this typically means installing or ensuring Firefox is correctly installed and its dependencies are met (e.g., `sudo apt-get install firefox` or `sudo apt-get install libxul-dev` if available for your distribution).

Upgrade

Version history

2.0.7latest on PyPI · released May 16, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

30 hits · last 30 days

node

Resources

githubhttps://github.com/vgalin/html2image ↗

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

changeloghttps://github.com/vgalin/html2image/releases ↗