thumbspage — Image-Gallery Web Pages for Folders

This Python program builds static 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. As such, thumbspage makes general photo galleries, useful in a variety of contexts.


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

Given an image-files folder, thumbspage generates thumbnail images, a top-level HTML index page, and optional HTML image viewer pages with next/previous navigation links. When clicked or tapped, thumbnails on the index page open either built viewer pages or browser-native image displays. The index page can also include bullet links to any nested subfolders in the images folder, and images can be previewed with a basic GUI-mode viewer.

Run parameters—image folder path, thumbs per row, thumbs max size, and viewer-pages option—are input interactively in the console. For more control, custom HTML header and footer sections for the index page can be provided in the images folder; colors can be customized in settings; 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 library available here. Any platform supported by both of these systems can run thumbspage, including Mac OS, Windows, Linux, and Android. There's an update on Pillow installs here.

The pages this program creates work on all commonly used desktop and mobile browsers. Any recent version of Chrome, Firefox, Safari, Edge, and Internet Explorer should suffice—including the 12 tested among Mac OS, Windows and Linux, and the 10 tested across Android and iOS.

Recent releases have added full Unicode support [1.3]; improved styling and mobile support [1.4]; optional viewer pages for custom image display [1.5]; and both automatic rotation for tilted images and their thumbs, and JavaScript-based dynamic image scaling for viewer pages (though pages still function without it) [1.6].


thumbspage comes with complete usage examples, in-program documentation, and a comprehensive HTML user guide with information for both end users and developers. 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 demo sites:

Latest examples:


thumbspage is provided as open-source and portable source code that you run with a Python installed separately (usually in Terminal on Mac OS 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.

Note: most of the zipfile's size is taken up by its top-level examples folder, which can be freely removed (albeit at the expense of breaking links in your local copy of the user guide). To reclaim space, delete this folder after unzipping, view its online content here, and use the online copy of the user guide here.

Fetch and view:

This program was last changed: October 28, 2018.

Android update:

This program was repackaged in February 2019 to include a minor change in this module which avoids a tkinter dependency except when using the simple and obscure GUI-viewer mode. This did not impact thumbspage's behavior or results (and doesn't constitute a new version), but allows it to be run in contexts that support Pillow but not tkinter. Though this change is generally helpful, its main impetus was Python Android apps. For instance, thumbspage is now usable on Android in both the tkinter-less Termux after running both this command (sans its "-y") and pip install Pillow, as well as the tkinter-aware Pydroid 3 after running the same pip command in its Terminal or using its Pip.

Related programs:

For a GUI-based image viewer, also see PyGadgets' PyPhoto—which acquired thumbspage's image rotation (more details here). For a photo-folder organizer tool, see tagpix. For a script that zips and uploads images and a non-thumbnail index page, see pixindex. And for more code examples, see the programs page.

[Home] Books Programs Blog Python Author Training Search Email ©M.Lutz