thumbspage — Turn Folders into HTML Image Galleries

This Python program builds web pages for user-friendly viewing of all the images in a folder. Its results do not require a web server, and can be viewed in any desktop or mobile browser, both offline and online. They may also be easily customized, and can be enhanced with notes when it's useful to narrate your pictures. As such, thumbspage makes general image galleries, useful in a wide variety of contexts, including documentation, photo sharing, and regular viewing.

Click this page's images for quick live demos. Its contents:


thumbspage allows you to view or display a folder of photos and other images in a web browser, in a format that's both simple and noticeably better than browser defaults.

The thumbspage script automatically generates all the scaffolding needed to make this work. Given an image-files folder, along with any gallery options you choose to provide, it builds:

➤ Thumbnail images of any size
➤ An HTML index page in one of three flavors
➤ And one HTML viewer page per image

When clicked or tapped, thumbnails on the index page open viewer pages by default, but can also open browser-native displays. The index page may also include bullet links to nested subfolders in the images folder. Viewer pages in turn display the full-size image, automatically scaled to the display. They also come with navigation links, slideshow and fullscreen toggles, and info and note popups, and support swipes on touch displays.

Run parameters—image-folder path, thumbs per row, thumbs max size, and viewer-pages option—may be input interactively in the console, or provided by scripts or commands. For more control, custom HTML header and footer sections for the index page can be provided in the images folder; colors and much more can be customized in the configs file or command-line arguments; and the program's viewer-page template may be changed as desired.

The generated index page, along with a subfolder containing thumbnail images and generated viewer pages, are created in the images folder itself. Open the generated index page there (index.html by default) to view results, and package the complete images folder to publish (e.g., copy into your product, or zip and upload to your website).


This program uses and requires Python 3.X, plus the 3rd-party Pillow image-processing library. Any platform supported by both of these systems can run thumbspage, including macOS, Windows, Linux, and Android. For more on building galleries, see the creators section of the User Guide.

The pages this program creates use a portable combination of HTML, CSS, and JavaScript, and work on all commonly used desktop and mobile browsers. Any recent version of Chrome, Firefox, Safari, Edge, and Internet Explorer should suffice—including the more than 12 tested among macOS, Windows, and Linux, and the 10+ tested across Android and iOS. For more on viewing galleries, see the consumers section of the User Guide.

Recent Updates

thumbspage has been actively developed since its 2016 inception. Its recent releases have added:


thumbspage is used for all the galleries on this website (roughly 50 at last count), and comes with complete usage examples, in-program documentation, and a comprehensive HTML User Guide with information for both gallery viewers and builders. See the resources listed below for more details.

If you prefer to learn by example, study the demo sites here and here for a sparse but quick tutorial. For illustration, these sites use custom headers and settings, which you don't need to code if the defaults work for your galleries.

The Docs

The Code

Live Demos





thumbspage is provided as open-source and portable source code that you run with a Python installed separately (for example, in Terminal on macOS and Linux, Command Prompt on Windows, or a mobile-platform app). Use the following links to either fetch thumbspage and unzip it on your computer, or view its complete unzipped content online.

New: because its examples folder surpassed 200M in 2.1, thumbspage can now be downloaded in a program-only zip, which contains the complete runnable program, but omits the examples folder, and ships with a User Guide whose example links have all been adjusted to open online copies. Select the first download link below to fetch this new package, and save both space and download time. Other links download the full package as before or just the examples folder itself, and all downloads unzip to a thumbspage folder. You can also view online copies of the examples and guide.

Fetch and Browse



What's New

This program was last changed: May 9, 2022.

Its latest update adds support for per-image notes, and recent versions have added swipe gestures on touch displays, configuration by command-line arguments, thumbnail quality enhancements, dynamic index-page layout, and slideshows. See also the recent-changes list above.

Related Programs

For more code examples, see the Programs page on this website.

[Home page] Books Code Blog Python Author Train Find ©M.Lutz