Marcin Owsiany


mamgal - a program for creating static image galleries


  mamgal <directory>


mamgal recursively scans a directory and turns it into a gallery, that is - creates HTML files for browsing pictures within this directory. If the directory already contains a gallery, it tries to run as fast as possible, by only refreshing the files that it needs to, based on file modification timestamps.

When successful, mamgal prints nothing and exits 0.


MaMGal was inspired by imageindex(1) and as such aims for a similar featureset but higher efficiency and better code architecture.

  • Index and slide views, simple layouts.

  • Image captions extracted from comments embedded in images themselves. This way your photo descriptions will never get lost.

  • Static HTML output, no need for PHP or other server-side execution support.

  • Designed with efficiency in mind - only reads and processes the files which were modified since the last run.

  • Image creation time extracted from EXIF metadata.

Supported images

For the purpose of creating icons and slides, MaMGal supports the same images as ImageMagick and the same films as mplayer. However it decides whether a file is an image, film or something else, based on file extension. Please report any file extensions that should be treated as an image or film, but are not.

Created files

In each directory mamgal creates an 'index.html' and a number of hidden files and directories whose names start with '.mamgal-':


an empty marker file placed in the gallery root directory


a directory containing HTML files presenting one image each


a directory containing images scaled to be viewable on screen when shown within the slides


a directory containing "iconized" versions of images


a montage image showing the contents of the given directory


a stylesheet for the HTML files in the given tree


a temporary file that might be left over from a crash


MaMGal was designed with efficiency in mind, for example:

  • loads image data or metadata lazily, only when (and if) it needs it,

  • only processes files when it needs to refresh or create an output file when it is stale or missing,

  • runs as a single process, does not reexecute itself when recursing,

  • uses Perl calls and ImageMagick library to load and scale images, create and delete files, rather than executing external shell commands to do this (mplayer being the only exception).

Here is some example data of processing 15GB worth of images (9100 files in a tree of 528 directories), compared to imageindex(1):


3 hours, 96%CPU usage, 170K major + 227M minor pagefaults


1.5 hours, 92%CPU usage, 146K major + 102M minor pagefaults

re-run on a freshly generated gallery:

51 minutes, 89%CPU usage, 155K major + 103M minor pagefaults


3.5 minutes, 58%CPU usage, 115 major + 1.7M minor pagefaults

Name and History

MaMGal stands for "Marcin and Magda Gallery", as it was initially written to create my and my then-fiancée's photo collection. In the past I had been using imageindex(1) for that, but with time our collection grew too large to be processed with it in a timely manner, as imageindex took its time to read each picture on every run. Therefore I came up with an idea for a gallery program that would only process pictures that changed since the last run, and had a test suite that would make it safer to modify.


MaMGal trusts the files it reads. It currently does not properly escape all input read from the images before embedding it in the files it produces, potentially leading to XSS-like vulnerabilities, if the input files are coming from an untrusted source. This will probably be improved in the future.


Root directory

Note that the directory specified on the command line is treated as the root of the gallery, that is a directory that has no links to its parent directory. Therefore to refresh a gallery you always need to run mamgal with the root directory as an argument. (Otherwise, the subdirectory you specify will itself turn into a root directory.)

Duplicate Description Suppression

In the "index" view, if an entry's description is the same as its immediate predecessor's description, then it is omitted. This way you can have identical descriptions embedded in multiple images, but the index view is not cluttered with them.


MaMGal is Copyright 2007-2011 Marcin Owsiany <>


mplayer(1), jhead(1), imageindex(1), Image::Info(3), Image::ExifTool(3)


This program 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 2 of the License, or (at your option) any later version.

Please see the README file for more copyright and license information.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 170:

Non-ASCII character seen before =encoding in 'then-fiancée's'. Assuming UTF-8