Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

PyThumb -- Generate Thumbnails of Documents

PyThumb is a free Python-based tool to generate thumbnails for all kinds of documents or websites. It can be used as a library for other Python software or through a web interface, which is for example available as a Docker image.

This will be a tool to create thumbnails for whatever.. ;-)

It is intented to run as a Docker container, as it has many dependencies...

key features:

  • several formats
  • as library or web application
  • docker
  • thus available for multiple languages (not just python!!)

supported formats:

  • zip (will try to find images in the zip and use the one that has 'cover' in its name, or the largest image)

output always in PNG format


The PyThumb tool requires quite a lot of other software to parse and convert documents:

  • cutycapt
  • libre office
  • image magic
  • ps2pdf
  • python-magic

It is therefore recommended to run it using the corresponding Docker container.


As a Library


general version: thumb from file

special functions -> thumb from zip etc may fail (return false) then use thumb from name

As Executable

Through Web

you can run a tiny web server that generates the thumbnails


  • --ip the IP address of the web server. Default is, which will listen to all available address. Use to just listen to localhost.

does not support SSL -- use proxies such as nginx

from website:

curl -v -F target=  localhost:12346 > /tmp/thumb.png

from file:

maxwitdh maxheight

need to crop, because image magic may fail etc... cropwidth : default 10000, but for websites that may look ugly... if you want to see the first screen, set crop height for example to 1000

Run with Docker


see binfalse/pythumb

Running Tests

There are a number of tests shipped with that repository. You can find them in the test/ directory. The easiest way to run all the tests is to install python-nose and just run


from the root directory of this repository. python-nose will discover and run all the tests.

Run nosetests with enhanced verbosity to find the resulting files in a newly created /test-results/ directory:

nosetests -v

The resulting files will be named as test.module-test_method-linenumber.png.

To get more information about the runs even if they all succeeded you may want to run

nosetests -v --nologcapture --nocapture

To just run a single test you may just use the default unittest module:

python -m unittest test.testepub

or call nosetests with the test-file as an argument:

nosetests test/

This will run all the tests defined in test/

To see the code-coverage of the unit tests run nosetests with the following arguments:

nosetests --with-coverage --cover-erase --cover-package=pythumb --cover-html

This will show an output such as:

Name                  Stmts   Miss  Cover   Missing
pythumb/       8      4    50%   6-9
pythumb/      310     18    94%   167, 196-197, 336-338, 355-357, 373-374, 381, 443-444, 452-453, 543, 554
TOTAL                   318     22    93%
Ran 44 tests in 38.982s


Thus, here we have a code-coverage of 94%, which is probably in the meantime much higher ;-)

A detailed coverage report will then also be available in cover/index.html.


PyThumb is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with PyThumb.  If not, see <>.


Python Thumbnail Generator







No releases published


No packages published