Skip to main content

Package acting as a wrapper around the headless mode of existing web browsers to generate images from URLs and from HTML+CSS strings or files.

Project description

html2image logo

PyPI PyPI PyPI GitHub GitHub

PyPI Package GitHub Repository

A lightweight Python package acting a wrapper around the headless mode of existing web browsers, allowing images generation from HTML/CSS strings, files and URLs.

 

This package has been tested on Windows, Ubuntu (desktop and server) and MacOS. It is currently in a work in progress stage. If you encounter any problem or difficulties while using it, feel free to open an issue on the GitHub page of this project. Feedback is also welcome!

Principle

Most web browsers have a Headless Mode, which is a way to run them without displaying any graphical interface. Headless mode is mainly used for automated testings but also comes in handy if you want to take screenshots of web pages that are exact replicas of what you would see on your screen if you were using the browser yourself.

However, for the sake of taking screenshots, headless mode is not very convenient to use. HTML2Image aims to hide the inconveniences of the browsers' headless modes while adding useful features such as allowing to create an image from as little as a string.

For more information about headless modes :

Installation

HTML2Image is published on PyPI and can be installed through pip:

pip install --upgrade html2image

In addition to this package, at least one of the following browsers must be installed on your machine :

  • Google Chrome (Windows, MacOS)
  • Chromium Browser (Linux)
  • Microsoft Edge

Usage

First, import the package and instantiate it

from html2image import Html2Image
hti = Html2Image()

Multiple arguments can be passed to the constructor:

  • browser : Browser that will be used, can be set to 'chrome' (default) or 'edge'.
  • browser_executable : The path or the command that can be used to find the executable of a specific browser.
  • output_path : Path to the folder to which taken screenshots will be outputed. Default is the current working directory of your python program.
  • size : 2-Tuple representing the size of the screenshots that will be taken. Default value is (1920, 1080).
  • temp_path : Path that will be used to put together different resources when screenshotting strings of files. Default value is %TEMP%/html2image on Windows, and /tmp/html2image on Linux and MacOS.
  • keep_temp_files : Pass True to this argument to not automatically remove temporary files created in temp_path. Default is False.

Example:

hti = Html2Image(size=(500, 200))

You can also change these values later:

hti.size = (500, 200)

Then take a screenshot

The screenshot method is the basis of this package, most of the time, you won't need to use anything else. It can take screenshots of a lot of things :

  • URLs via the url parameter;
  • HTML and CSS files via the html_file and css_file parameters;
  • HTML and CSS strings via the html_str and css_str parameters;
  • and "other" types of files via the other_file parameter (try it with .svg files!).

And you can also (optional):

  • Change the size of the screenshots using the size parameter;
  • Save the screenshots as a specific name using the save_as parameter.

N.B. : The screenshot method returns a list containing the path(s) of the screenshot(s) it took.

A few examples

  • URL to image
hti.screenshot(url='https://www.python.org', save_as='python_org.png')
  • HTML & CSS strings to image
html = """<h1> An interesting title </h1> This page will be red"""
css = "body {background: red;}"

hti.screenshot(html_str=html, css_str=css, save_as='red_page.png')
  • HTML & CSS files to image
hti.screenshot(
    html_file='blue_page.html', css_file='blue_background.css',
    save_as='blue_page.png'
)
  • Other files to image
hti.screenshot(other_file='star.svg')
  • Change the screenshots' size
hti.screenshot(other_file='star.svg', size=(500, 500))

Click to show all the images generated with all the code above sample_url_to_img.png sample_strings_to_img sample_files_to_img sample_other_to_img sample_other_50_50

  • Change the directory to which the screenshots are saved
hti = Html2Image(output_path='my_screenshot_folder')

OR

hti.output_path = 'my_screenshot_folder'

N.B. : the output path will be changed for all future screenshots.


Use lists in place of any parameters while using the screenshot method

  • Screenshot multiple objects using only one filename, or one filename per file:
# create three files from one filename
hti.screenshot(html_str=['A', 'B', 'C'], save_as='ABC.png')
# outputs ABC_0.png, ABC_1.png, ABC_2.png

# create three files from from different filenames
hti.screenshot(html_str=['A', 'B', 'C'], save_as=['A.png', 'B.png', 'C.png'])
# outputs A.png, B.png, C.png
  • Take multiple screenshots with the same size
# take four screenshots with a resolution of 100*50
hti.screenshot(
    html_str=['A', 'B', 'C', 'D']
    size=(100, 50)
)
  • Take multiple screenshots with different sizes
# take four screenshots with different resolutions from three given sizes
hti.screenshot(
    html_str=['A', 'B', 'C', 'D'],
    size=[(100, 50), (100, 100), (50, 50)]
)
# respectively 100*50, 100*100, 50*50, 50*50
# if not enough sizes are given, the last size in the list will be repeated
  • Apply CSS string(s) to multiple HTML string(s)
# screenshot two html strings and apply css strings on both
hti.screenshot(
    html_str=['A', 'B'],
    css_str='body {background: red;}'
)

# screenshot two html strings and apply multiple css strings on both
hti.screenshot(
    html_str=['A', 'B'],
    css_str=['body {background: red;}', 'body {font-size: 50px;}']
)

# screenshot one html string and apply multiple css strings on it
hti.screenshot(
    html_str='A',
    css_str=['body {background: red;}', 'body {font-size: 50px;}']
)

  • Retrieve the path of the generated file(s)
    The screenshot method returns a list containing the path(s) of the screenshot(s):
paths = hti.screenshot(
    html_str=['A', 'B', 'C'],
    save_as="letters.png",
)

print(paths)
# >>> ['D:\\myFiles\\letters_0.png', 'D:\\myFiles\\letters_1.png', 'D:\\myFiles\\letters_2.png']

Change browser flags

In some cases, you may need to change the flags that are used to run the headless mode of a browser.

Flags can be used to:

  • Change the default background color of the pages;
  • Hide the scrollbar;
  • Add delay before taking a screenshot;
  • Allow you to use Html2Image when you're root, as you will have to specify the --no-sandbox flag;

You can find the full list of Chrome / Chromium flags here.

There are two ways to specify custom flags:

# At the object instanciation
hti = Html2image(custom_flags=['--my_flag', '--my_other_flag=value'])

# Afterwards
hti.browser.flags = ['--my_flag', '--my_other_flag=value']
  • Flags example use-case: adding a delay before taking a screenshot

With Chrome / Chromium, screenshots are fired directly after there is no more "pending network fetches", but you may sometimes want to add a delay before taking a screenshot, to wait for animations to end for example. There is a flag for this purpose, --virtual-time-budget=VALUE_IN_MILLISECONDS. You can use it like so:

hti = Html2Image(
    custom_flags=['--virtual-time-budget=10000', '--hide-scrollbars']
)

hti.screenshot(url='http://example.org')
  • Default flags

For ease of use, some flags are set by default. However default flags are not used if you decide to specify custom_flags or change the value of browser.flags:

# Taking a look at the default flags
>>> hti = Html2Image()
>>> hti.browser.flags
['--default-background-color=000000', '--hide-scrollbars']

# Changing the value of browser.flags gets rid of the default flags.
>>> hti.browser.flags = ['--1', '--2']
>>> hti.browser.flags
['--1', '--2'] 

# Using the custom_flags parameter gets rid of the default flags.
>>> hti = Html2Image(custom_flags=['--a', '--b'])
>>> hti.browser.flags
['--a', '--b']

Using the CLI

HTML2image comes with a Command Line Interface which you can use to generate screenshots from files and urls on the go.

The CLI is a work in progress and may be subject to changes. You can call it by typing hti or html2image into a terminal.

argument description example
-h, --help Shows the help message hti -h
-U, --urls Screenshots a list of URLs hti -U https://www.python.org
-H, --html Screenshots a list of HTML files hti -H file.html
-C, --css Attaches a CSS files to the HTML ones hti -H file.html -C style.css
-O, --other Screenshots a list of files of type "other" hti -O star.svg
-S, --save-as A list of the screenshot filename(s) hti -O star.svg -S star.png
-s, --size A list of the screenshot size(s) hti -O star.svg -s 50,50
-o, --output_path Change the output path of the screenshots (default is current working directory) hti star.svg -o screenshot_dir
-q, --quiet Disable all CLI's outputs hti --quiet
-v, --verbose More details, can help debugging hti --verbose
--chrome_path Specify a different chrome path
--temp_path Specify a different temp path (where the files are loaded)

... now within a Docker container !

You can also test the package and the CLI without having to install everything on your local machine, via a Docker container.

  • First git clone this repo
  • cd inside it
  • Build the image : docker build -t html2image .
  • Run and get inside the container : docker run -it html2image /bin/bash

Inside that container, the html2image package as well as chromium are installed.

You can load and execute a python script to use the package, or simply use the CLI.

On top of that, you can also use volumes to bind a container directory to your local machine directory, allowing you to retrieve the generated images, or even load some resources (HTML, CSS or Python files).

Testing

Only basic testing is available at the moment. To run tests, install the requirements (Pillow) and run PyTest at the root of the project:

pip install -r requirements-test.txt
python -m pytest

FAQ

  • Can I automatically take a full page screenshot?
    Sadly no, it is not easily possible. Html2Image relies on the headless mode of Chrome/Chromium browsers to take screenshots and there is no way to "ask" for a full page screenshot at the moment. If you know a way to take one (by estimating the page size for example) I would be happy to see it, so please open an issue or a discussion!

  • Can I add delay before taking a screenshot?
    Yes you can, please take a look at the Change browser flags section of the readme.

  • Can I speed up the screenshot taking process?
    Yes, when you are taking a lot of screenshots, you can achieve better "performances" using Parallel Processing or Multiprocessing methods. You can find an example of it here.

  • Can I make a cookie modal disappear?
    Yes and no. No because there is no options to do it magically and extensions are not supported in headless Chrome (The I don't care about cookies extension would have been useful in this case). Yes because you can make any element of a page disappear by retrieving its source code, modifying it as you wish, and finally screenshotting the modified source code.

TODO List

  • A nice CLI (currently in a WIP state).
  • Support of other browsers (such as Firefox when their screenshot feature will work).
  • PDF generation?
  • Contributing, issue templates, pull request template, code of conduct.

If you see any typos or notice things that are oddly said, feel free to create an issue or a pull request.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

html2image-2.0.4.1.tar.gz (21.7 kB view details)

Uploaded Source

Built Distribution

html2image-2.0.4.1-py3-none-any.whl (27.8 kB view details)

Uploaded Python 3

File details

Details for the file html2image-2.0.4.1.tar.gz.

File metadata

  • Download URL: html2image-2.0.4.1.tar.gz
  • Upload date:
  • Size: 21.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.4 CPython/3.9.6 Windows/10

File hashes

Hashes for html2image-2.0.4.1.tar.gz
Algorithm Hash digest
SHA256 0af07807e1362e6100efd8c3a0d71b3c2baa0e6fb503007513b59b4d0b906fb4
MD5 9ecc98520da3a74d7f5fd99982715e3a
BLAKE2b-256 2771d64f63be63c0e040f787b4f099681ca2f3dfc5c24fa01ad7419f87883d28

See more details on using hashes here.

File details

Details for the file html2image-2.0.4.1-py3-none-any.whl.

File metadata

  • Download URL: html2image-2.0.4.1-py3-none-any.whl
  • Upload date:
  • Size: 27.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.4 CPython/3.9.6 Windows/10

File hashes

Hashes for html2image-2.0.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 5f106cb2a53523b4435c6260999566e4872302716427d841693c9b9b67caf6d8
MD5 32c4df00efb4127e06463727b109e3e0
BLAKE2b-256 7fa6cbfde96436b208b7653fd54e053c884590e6e46c6d8bedadad942198fbfa

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page