Summary: A thumbnail picture gallery for PmWiki
Version: 20240430
Prerequisites: PmWiki 2.2.58 or later, latest stable recommended
Maintainer: Petko
Discussion: ThumbList-Talk
Download: thumblist2.zipΔ (alt. download:
Users: +14
License: GPL3+

Questions answered by this recipe

Is there a powerful PmWiki picture gallery with thumbnails?

Horizontal list of thumbs
All thumbnails on this page come from Public Domain collections at Wikimedia Commons.[1]

Table of contents

A tabled version (:thumblist cols=3:)


Thumblist² is a feature-rich picture gallery, for one or many thumbnails. The script will automatically create smaller copies of the pictures, and will display them, with links to the original ones.

I wrote this recipe for a simpler way to display a clickable thumbnail list. All you need is to upload or copy the files and add the command (:thumblist:) to the page.

Features :

  • Will work also with PHP Safe mode.
  • Doesn't need any external programs or configurations, just GD (the php built-in image functions).
  • Able to use ImageMagick's convert.
  • All thumbnails are cached, so they are only created once or if the original has changed.
  • The full gallery can be cached too (see Supercache).
  • Will work even with $EnableDirectDownload=0; and with all possible $UploadPrefixFmt settings.
  • There is no need to set other permissions, or other directories etc. as thumbnails are stored in the same upload directory as the originals.
  • If uploading in PmWiki works, you should be able to use this command immediately.
  • Individual thumbnail captions, as well as EXIF data extraction are available.

The recipe was meant to be simple and lightweight and still can be used easily, but grew to become a powerful gallery script. It allows very flexible configurations.

Note: Thumblist became a beast of an online gallery that does everything. If you do not need all its features, but prefer a smaller, simpler replacement, check out Mini. See also Mini vs Thumblist2 - discussion at the mailing list.

Examples in the wild

Please edit this page and add your publicly visible galleries in this section.


If you upgrade from a previous version, please read the release notes for important changes.

NOTE! Thumblist 2 is a new, different script and some things have changed. If you upgrade, it is recommended that you read What's new in version 2.

To install a new version:

  • Download the archive thumblist2.zipΔ (alt. download:
  • Copy the files thumblist2.php and thumblist2-actions.php to your /cookbook directory.
  • Add this line to your config.php:
  • Copy this CSS code to your stylesheet (you may adapt it for your needs):
img.thumbs {
 border:1px solid #dddddd; margin:2px; padding:4px; vertical-align: middle; }
img.thumbs:hover, table.thumbtable td.thumbtd div.img:hover {
 border:1px solid red; }
table.thumbtable img.thumbs { border: 0; padding:0; }
table.thumbtable td.thumbtd { margin:4px; padding:2px; }
table.thumbtable td.thumbtd:hover { border-color:red; }
table.thumbtable { border:1px solid #cccccc; }
table.thumbtable td.thumbtd div.img {
 border: 1px solid #dddddd; text-align: center; }
.caption {
 font-size:.8em; overflow:hidden; padding:0px; line-height:1.1em; }
img.current, table.thumbtable td.thumbtd div.current {
 border-color: red; }

See also PmWiki.UploadsAdmin. Thumblist² is particularly comfortable with the setting $UploadPrefixFmt = '/$Group/$Name'; (all pictures in a distinct directory per page).

Vertical list of thumbs

Basic usage

Please see also Notes below.

Three new markup commands can be used with this recipe: (:thumb:), (:thumblist:) and (:thumbgallery:).

  • (:thumblist:) will display a gallery of all pictures, attached to the current page (recommended).
  • (:thumb:) will display one thumbnail: use (:thumb Group.Page/My_picture.jpg:)
  • (:thumbgallery:)...(:thumbgalleryend:) will display a list of selected pictures.


To just list thumbnails of all pictures, attached to the current page, write (:thumblist:).

Thumblist and thumbgallery commands can have many parameters (:thumblist Group.Page px=128 cols=4 name="paris_*":), all of which are optional.

  • Group.Page - to create a gallery of pictures uploaded in another Group (or Group.Page, depending on your wiki settings[2]), add it immediately after thumblist or thumbgallery: (:thumblist Group.Page:)
  • px=128 - the size in pixels of the thumbnails. This is the height or the width, and the default is 128.
  • name="paris_*.jpg|france*.jpg" - to display only some files, whose name matches a pattern, example "paris_01.jpg", "paris_02.jpg"... Files without this pattern will be skipped; if not set, will display all files. (*=any string, ?=one character, case insensitive, separate patterns with "|" if you have more than one).
  • skip="*.gif|*.png" - skip some pictures (*=any string, ?=one character, case insensitive, separate patterns with "|" if you have more than one). If not set, will display all files. This is the reverse of the name option.
  • cols=4 - this command indicates that (1) the thumbnails will be in a table, and (2) the table will have 4 columns (4 thumbnails on every line). Without this command cols=, the thumbnails will be displayed "inline", all with the same height (from px=).
    • additional optional parameters for "table mode" border, bgcolor, cellpadding, cellspacing, rules, style, align, caption (standard HTML-attributes). For example the command (:thumblist cols=3 caption="Pictures from Miami" align=center:) will display a centered table with a caption "Pictures from Miami" usually on top of the table.
  • bgcolor=#123456 - for transparent PNGs or GIFs you may need to set the thumbnail's background (default is white, #ffffff; only accepts hexadecimal format for the color). This is usually the same as the background color of your page.
  • supercache=1 -- enable caching of the whole gallery (recommended in some cases, see Supercache).

Single thumbnail

Single thumbnail

  • Use the command (:thumb my_picture.jpg:), or with extended switches (:thumb Group.Page/my_picture.jpg width=100 titlefmt="Photo from Paris (%kk)" usetemplate=1:).
  • You can use "width=100" to define the thumbnail width, or (like for the thumblist command), "px=100" to define the thumbnail height. If none set, the default thumbnail "height" will be used (for historical reasons, usually 128px).

Single thumbnail with a caption

Use (:thumb Everest.jpg captionfmt="View from Mount Everest" align=right:). When you set the parameter "captionfmt" for a single thumbnail, it is transformed in a one-cell table containing the thumbnail and the caption. If you set the parameter align=right or align=left, the page text will float next to the thumbnail.

ThumbGallery: displaying selected pictures

Use the markup:

(:thumbgallery cols=3:)
pic1.jpg | Caption
pic2.jpg | Another caption
  • The parameters are the same as for the (:thumblist:) command - you can use cols=3, px=100, bgcolor=#ffff00 etc.
  • Use (:thumbgallery OtherGroup.OtherPage:) if the pictures are attached to another page.
  • The "cols=" parameter is required in order to display the individual captions (must be >0).

ThumbGallery in "ThumbList mode"

From version 2007-01-14 on, it is possible to combine the (:thumblist:) and (:thumbgallery:) commands.

Use the markup:

(:thumbgallery cols=3 tlmode=1:)
pic1.jpg | Caption
pic2.jpg | Another caption
  • The markup is the same as in the (:thumbgallery:) command, only with an added parameter tlmode=1.
  • When tlmode=1 is enabled:
    • all files are read, and sorted, as in (:thumblist:)
    • their "captions" are taken from the wiki page, between (:thumbgallery:) and (:thumbgalleryend:), if they exist.
  • If you set instead tlmode=2 : only the filenames will be listed, easy way to copy them and paste them in the page.

See also the $ThumbList['tlmode'] admin variable.

Please see also Notes below.


Supercache is a special mode that will cache the whole thumblist (the gallery). It is activated with (:thumblist [other options] supercache=1:).

Consider: on every page view, all the upload directory is read, and all the files are checked if they are pictures, and then if there exist thumbnails for them. If you have like 400-500 files, or even 50 in the upload directory, even if the thumbnails are already created, this check can take much time and server load. The Supercache will do this check once and will cache the thumblist, so on the next page view, it will only load the cached thumblist. This can be hundreds of times faster and lighter! If you change the page, or if you call the action "purgethumbs", the Supercache will be regenerated again.

It is recommended to use the Supercache, if you do not change often the files in your gallery, if you don't add more and more files to the same page, because with the Supercache, the script will not check for new files in the upload directory, or for deleted ones. Actually, if you have more (views) than (edits + new uploads) for one page, it is better to enable the Supercache for that page.

Note: Supercached thumblists may not work inside or after conditional expressions. If you have conditionals that change the thumblists, or change the order of the thumblists in the page, you need to indicate a different supercache-id-number for each gallery by manually choosing a number>1000:

(:if auth admin:)
(:thumblist supercache=1001:)
(:thumblist skip=*private* supercache=1002:)

If you have a conditional that hides/shows a thumblist, and in the same page you have other thumb(list)s, they all need to have manually set different IDs>1000 in order to be properly supercached.

Purging the thumbnail cache

If you made lots of tests, the thumbnails are all cached, so there is an action "purgethumbs" to remove all cache (thumbnails and supercache) in the current upload directory. Example: [[{$Name}?action=purgethumbs]].

Note that the cache is stored in the upload directory where the original files are, so if you are using (:thumblist OtherGroup.OtherPage:), to purge the cache you need [[OtherGroup.OtherPage?action=purgethumbs]].

See also: AutoPurge.

Advanced users

Additional parameters and settings for more advanced users:

  • Note about dimensions. px= means the height of inline lists, the maximal dimension (width or height) in table mode. You can also select width= to fix the width, or height= to fix the height of the thumbnails. These parameters are not compatible one with another, if used at the same time, px= overrides width= which overrides height=.
  • count=20, count=5..10, count=15.. -- subset of thumbnails to display. If not set, will display all pictures in the upload directory. count=20 means from number 1 to 20, count=5..10 means from 5 to 10 inclusive, count=15.. means from 15 to the end. It is similar to the pagelist's count parameter, but only accepts positive numbers.
  • perpage=20 -- automatic subset of thumbnails to display; with this parameter, large thumblists are automatically split into sub-pages with a link trail below. Demo.
    • perpagenav=2 -- position of the sub-page-link-trail (0:none; 1:above the thumbnails; 2: below; 3:both).
  • titlefmt="?f: ?wx?h (?kk)" for the tooltip format. Default is "?f: ?wx?h, ?kk (?t)", see Question-variables
  • captionfmt="?f: ?wx?h (?kk)" - for the individual picture caption below the thumbnail (default is none), see Question-variables
  • link=0 - default - link to original when needed (ie original is larger than thumbnail);
    • link=-1 - never link to the originals;
    • link=1 - always link to the originals, even if smaller than the thumbnail;
    • link=2 - will link not to the original picture, but to the wiki-page where the file is uploaded. Demo.
    • link=Group.Page - will link not to the original picture, but to the wiki-page Group.Page (needs a full pagename). Demo.
    • use [[ | (:thumb example.jpg link=-1:)]] with link=-1 to link to an external page
  • order=name - sort the thumbnails according some properties of the originals, before a subset selection with count=. May be name, ext, time, size, width, height, ratio or random, and start with '-' to reverse it. Only one ordering property can be used. Demo.
    • order2=name - sort the thumbnails according some properties of the originals, after a subset selection with count=. Only one ordering property can be used.
  • quiet=3 - no output on errors/files not found. Set to 1 to suppress warnings, 2 to disable Attach: links to non-existant files, 3 to disable both. Default is 0 : show warnings and attach links.
  • imcl=shadow (only valid with ImageMagick) - use a different command line template defined in $ThumbList['IMCLTpl'].
  • htmlpx=0 instructs not to set width and height attributes in the <img/> tags for thumbnails (default is to set them).


There are a number of case-sensitive variables that are set for every thumbnail: you can use them inside the parameters titlefmt, captionfmt and also in the "captions" of the (:thumbgallery:) markup, and in the HTML snippets defined in the array $ThumbList['_tmpl'] (for advanced administrators).

The meanings of the variables are as follows (for the original picture):

  • ?f = filename.ext
  • ?i = filename without extension
  • ?w, ?h, ?r, ?a = width and height in pixels, ratio (width/height), area (width*height)
  • ?b and ?k = file size in bytes and kilobytes
    • ?s file size in human-readable format in binary units multiple of 1024, with a suffix "b" (bytes), "k" (kibibytes), or "M" (mebibytes)
    • ?S file size in human-readable format in decimal units multiple of 1000, with a suffix "b" (bytes), "k" (kilobytes), or "M" (megabytes). This requires PmWiki 2.3.32 or more recent.
  • ?t = file modification time (i.e. upload time, not EXIF shooting time)
  • ?? = the question mark

For advanced users:

  • ?a = the number of pixels (area) of the original picture
  • ?P and ?p = the full name (Group.Page) and the name (Page) of the wiki page where the thumbnails are uploaded
  • ?G = the gallery number for that page
  • ?N will add line breaks &#10; in titlefmt and "<br/>" in the captionfmt.
  • ?U and ?u - the original picture's Url and the thumbnail's url (you should know what you're doing!).
  • ?L - the actual link on the thumbnail (may be to the original, to another page, or to a template trail).

Note: these four variables (?N, ?u, ?U, ?L) are not transposed into template variables.

EXIF extraction is enabled, if you use one of the following case-sensitive question-variables (which makes the script slower):

  • ?W and ?H - EXIF width and height in pixels
  • ?T - date/time of the picture creation (EXIF shooting time)
  • ?M and ?m - Camera Manufacturer and model
  • ?E and ?I - Exposure time and ISO speed rating
  • ?A and ?F - Aperture number and Focal length
  • ?C - User comments for the file (added by the camera or by a picture editing software)

Not all pictures contain EXIF data.

Template trails: displaying the original pictures inside a wiki page

If you wish to display the original pictures inside a wiki page instead of linking directly to the file, use the option (:thumblist usetemplate=1:).

The image will be shown inside an empty wiki page with your current skin. You can personalize this page by creating page templates. The templates are the wiki pages [[{$FullName}-ImageTemplate]] or [[{$Group}.ImageTemplate]] or [[{$SiteGroup}.ImageTemplate]] (whichever is first found; if none found, will display only the picture). Just create and edit the page Site.ImageTemplate, and it will be used for all your galleries.

An example template would be:

!! $[Displaying] {*$UpFile}
%p center% {*$PrevLink} [[{*$FullName}?action=browse | $[Back to gallery] ]] {*$NextLink}\\
(:title {*$Namespaced} / {*$UpFile}:)

For PmWiki versions older than 2.1.27 use {$FullName} instead of {*$FullName}.

From version 2008-02-08 on, it is possible to manually select another ImageTemplate page in each gallery page. To do this, add in the wiki page containing the thumblist, a new PageTextVariable called "ImageTemplate":

 (:thumblist usetemplate=1 [...]:)

where SomePage (or OtherGroup.SomePage) is your ImageTemplate. Demo.

In the template there are some new page variables:

  • {*$UpFile} = the file name, ex. my_picture.jpg
  • {*$UpDir} = the wiki page to which the image was uploaded, ex. Group.Page (may be different from the current page {*$FullName})
  • {*$UpDirUpFile} = a string like Group.Page/my_picture.jpg, easy to use in Attach:.
  • {*$UpDirUpFile2} = similar to the above but with spaces and special characters from the file name escaped. Note that this may require a very recent PmWiki version (2.3.30 or more recent) to work.
  • (for advanced users) {*$UpFilePage} = a virtual page name for single picture comments (the filename capitalized and only with allowed pagename characters), ex. Mypicturejpg. You can use this to set some individual file comment or description possibility, using other recipes (PmForm, Fox, AddDeleteLine2, etc.). For example:
    (:include FileComments/{*$UpFilePage}:) or (:include {*$UpFilePage}-comments:)
  • {*$PrevLink} and {*$NextLink} - links to previous and next image in the current gallery (empty if no prev/next). See an example.
  • {*$PrevThumb} and {*$NextThumb} - thumbnail links to previous and next image in the current gallery (empty if no prev/next). See an example.
  • All available question-variables (except ?n, ?N, ?u, ?U) are transposed into page variables and can be used in the template like this:
    • ?h={*$ThumbList_h},
    • ?w={*$ThumbList_w},
    • ?G={*$ThumbList_G} etc. (see question-variables for more).

In the template you can use directives like (:title {*$UpFile}:), (:noleft:), (:noaction:), (:nofooter:), etc. and a link like [[{*$FullName} | Back to gallery ]] to return to the original page.

For PmWiki versions older than 2.1.27, please use {$UpFile} instead of {*$UpFile}, {$UpDir} instead of {*$UpDir}, etc.

You can even use (:thumb "{*$UpDirUpFile}" width=600:) in the template, for example if the picture is 2000-3000 pixels and would break the layout, but do not set here the Supercache.

Advanced administrators: changing the default options

In your file config.php, before calling the script, you can change the default settings for the options.

  • $ThumbList['ShowErrors']=0; - Do not display warnings of problems (files not found etc.). Default is to display warnings.
  • $ThumbList['EnableMessages']=0; - Do not display supercache messages such as "Getting cache for Group.Page, gallery-trail X"
  • $ThumbList['Px'] = 100; - the default size of the thumbnails, for the option px= (default is 128).
  • $ThumbList['PerPage'] = 20; - the default number of the thumbnails in a subpage, see the parameter perpage= (default is 0: disabled). This can be overridden in a wiki page by the parameter perpage=.
    • $ThumbList['PerPageNav'] = 3; - the default position of the subpage link trail, see the parameter perpagenav= (default is 2: below). This can be overridden in a wiki page by the parameter perpagenav=.
  • $ThumbList['Px'] = 100; - the default size of the thumbnails, for the option px= (default is 128).
  • $ThumbList['TitleFormat'] = "?f: ?wx?h ?kk (?t)"; - change the default tooltip title format, see above.
    • $ThumbList['CaptionFormat'] = "?f: ?wx?h (?kk)"; - change the default individual picture caption format (default is none).
  • $ThumbList['BgColor'] = "#000000"; - if your page background is not white, set its color here (in the format #123456).
  • $ThumbList['Quality'] = 95; - the JPEG quality/compression (default is 90, 100 is best but bigger filesize)
  • $ThumbList['LinkOriginal']=1; - (default is 0) if the picture is equal or smaller than the expected thumbnail, it is shown instead of creating a thumbnail, and no link to the original, as it is allready shown; if set to 1, will always link to the original; if set to -1, will never link to the original. This can be overridden by the parameter link=.
  • $ThumbList['UseTmpl']=1; - to always use the templates.; set usetemplate=0 to override this eventually.
  • $ThumbList['PrevLink'] = "Previous"; and $ThumbList['NextLink'] = "Next"; - text of the prev-next links in the ImageTemplate trails, default are "<<" and ">>".
  • $ThumbList['AttachLinks']=1; - in "thumb" and "thumbgallery" mode, if the requested files are not found, Attach: links will be displayed for an easier upload. If set to 0, no attach links will be output.
  • $ThumbList['PurgeRedirectFmt'] = '$ScriptUrl/Cookbook/ThumbList?action=upload'; - to change the page displayed after purging the thumbnail cache: default is the upload page, set to '{$PageUrl}' to change it to the page itself.
  • $ThumbList['AllowedUploadPages'] = '*'; - specify a list of pages whose attached files may be displayed in a thumblist. You can use '{$Group}.*' for all pages in the current group, '{$FullName}' for the current page only, 'Photos*.*' for groups beginning with 'Photos', have excluded groups/pages '-Private.*,-Main.SecretPage' and combine the patterns with commas.
  • $ThumbList['TrailPx'] = 64; - set the default height for {$PrevThumb} and {$NextThumb} thumbnails in an Image template.
  • $ThumbList['tlmode'] = 1; - set the "Thumblist mode" as default for every thumbgallery (you don't have to write in pages tlmode=1).
  • $ThumbList['EnableThumbs'] = 1; - this variable controlls the thumbnail creation; set to 0 to disable thumbnails and effectively lock Thumblist (existing thumbnails are shown, non existing ones display only the tooltip title text with a link).
  • $ThumbList['_tmpl'] is an array containing all HTML snippets used to build the thumblists. If you define your own snippets before including the script, it will use them instead of the built-in ones. More...

Wiki markup in thumbgallery captions

It is now possible to have most wiki markups in thumbgallery captions. You can have links, colors and other inline formatting (bold, italics...).

The thumbnail tooltip titles from the thumbgallery has changed in version 2008-01-18, from

 photo.jpg | caption without markup | tooltip title


 photo.jpg"tooltip title" | caption with/without markup

(in both cases the tooltip title is not required).

This is similar to the PmWiki way of formatting pictures, as in PmWiki.Images.

If you already have many galleries using the tooltip titles the old way, you can switch back to the old way by setting in config.php the code:

 $ThumbList['EnableMarkup'] = 0;

This will disable links and other markup in the caption.


From version 83Q (2008-03-26) there is the new feature AutoPurge. In case too many thumbnails have been created, approximately the oldest 30% of them are deleted (if they are needed, they will be recreated on the next page view).

The AutoPurge parameters can be customized in config.php. The defaults values are:

  • $ThumbList['MaxThumbs'] = 3000; - maximum number of thumbnails for the whole wiki; if there are more, the oldest 30% of the maximum allowed number will be purged.
  • $ThumbList['DirThumbsRatio'] = 2; - maximum number of thumbnails for one upload directory (2 means 2 times the number of uploaded pictures).
  • $ThumbList['AutoPurgeRatio'] = 0.3; - amount of oldest thumbs to be purged (0.3 means 30%, 0.5 means half); this ratio is applied to the maximum allowed number of thumbnails, not to the actual number.
  • $ThumbList['AutoPurgeDelay'] = 1800; - seconds between the AutoPurge checks (1800sec=30min). Because scanning a very large number of files and directories may be CPU-intensive for the server, it is performed only when a thumbnail is created, and only if another check was not done in the delay (here: 30 min). This is why the numbers above are approximate.

To completely disable the AutoPurge function, set $ThumbList['AutoPurgeDelay'] = 0; in config.php.

ImageMagick settings (for very advanced administrators)

Using ImageMagick
  • $ThumbList['ImageMagickExe'] = '/usr/bin/convert'; - change from PHP's internal GD image functions to the powerfull ImageMagick's `convert`. Set here the path to the `convert` executable or link.

Note that under "PHP Safe mode" you may be unable to use `convert`, read this page for tips. Note that this configuration is intended for very advanced administrators. On most shared/cheap hostings this will not work.

  • $ThumbList['DefaultCLTpl'] = 'default'; - set here the default command line template for ImageMagick. The current version comes with 'default' and 'shadow' command lines, you can add more in the $ThumbList['IMCLTpl'] array below.

The next setting should be used only by very advanced users familiar with ImageMagick and PHP use of shell commands. If you are not, you may break your system and/or erase all your files.

  • $ThumbList['IMCLTpl']['tplname']='{%x} "{%P}" -thumbnail "{%w}x{%h}!" "{%p}"'; - add new command line template called "tplname". It can be called either by $ThumbList['DefaultCLTpl'] = 'tplname'; or by the parameter imcl=tplname. The command line template can have the following variables which are automatically replaced at runtime:
    • {%x} - the executable path (from $ThumbList['ImageMagickExe'])
    • {%W} and {%H} - original picture's width and height
    • {%w} and {%h} - thumbnail's width and height
      • you can have {%w+10} or {%h-4} to change dynamically these numbers.
    • {%c} - the color, defined in bgcolor= attribute (can be #123456 or #none, default is #ffffff)
    • {%q} - the output jpeg quality (from $ThumbList['Quality'])
    • {%P} - the path/name to the original picture in the upload directory
    • {%p} - the path/name to the thumbnail
    • {%RAND-6+6} - random number generator from -6 to +6.

See also : an ImageMagick manual.


As more and more people want additional features in the Thumblist, I decided to completely rewrite the script, so that everyone be able to adapt it for their needs. Instead of having an enormous program that does every possible thing found in online gallery software, Thumblist² is rather accepting every possible modification.

The new version is extremely flexible. It is fully configurable and all components are replaceable and extendable by user-defined ones : templates, ordering, user-defined swappable and derivable functions (much more in the spirit of PmWiki). It is possible and easy to write recipes/plug-ins modifying most aspects of your galleries.

We will write and add such recipes either here, or to the Thumblist² documentation site.

Currently, there are recipes like:

There are also a number of other pages demonstrating the built-in features and possibilities of Thumblist².


  • On the first run, all thumbnails are generated as the page renders. That is, on pages with very large number of thumbnails combined with a slow server, the script may not be able to create all the thumbnails at once (due to the max_execution_time limit). In that case, either put the thumbnails in several pages (fewer on each page), or reload the page again and again till all thumbnails are generated and cached (then it should be ok).
  • PHP is not meant to do heavy image processing, so the thumbnails may not work with very big images. Most default PHP installations (usually 8M memory) can handle maximum a 2 megapixel image (about 1600*1200 pixels, colored at 4 bytes/px). If you have problems with some pictures, try to resize them down a little: a picture of 1024*768 pixels is more than enough for most visitors' screens.
  • Spaces, international characters or other special characters are not recommended in the file names of the uploaded pictures, use at your own risk. If any such case happen to work, it would be unintended, unsupported and not guaranteed to work in future versions.
  • This recipe cannot be used together with the recipe Thumbnail Link To Image, as they use the same command (:thumb:).
  • If used together with Mini, this recipe should be included before Mini.

Change log / Release notes

Current (recommended) version is thumblist2.zipΔ (version 20240430). Comments and bug reports are welcome.

  • 20240420, 20240426, 20240430 : Updates for PHP 8.3 (reported by Simon).
  • 20240321 : Add question variable "?S" (human-readable file size in decimal units), suggested by Simon.
  • 20240319 : Add question variable "?s" (human-readable file size in binary units).
  • 20240217 : Fix previous and next links when a filename contains a "+" plus (reported by Simon).
  • 20240213 : Add {*$UpDirUpFile2}. Note that using this variable may need PmWiki 2.3.30 or more recent.
  • 20230118 : Add $ThumbList['CustVarFunction'], see Talk.
  • 20230115a : Fix for PHP 8.2.
  • 20230115 : Fix for some files with special characters could not be linked or have thumbnails generated (reported by Simon). Refactored logic for ImageTemplate page variables to prevent some errors with special characters. Update for PHP 8.
  • 20221217 : Update for PHP 8.
  • 20211217 : Update for PHP 8.
  • 20210618 : Fix for PHP 7.2-7.4 update (2 forgotten callbacks, only affected the imagemacick generation); update for PHP 8.
  • 20201104 (v80) : fix bug with ImageMagick configuration, reported by Matt Strauser.
  • 20200423 : mute some PHP notices, reported by Dfaure.
  • 20190903 : update for PHP 7.4.
  • 20190726 : in titlefmt change "?N" from vertical bar | to line break (requested by Simon)
  • 20190715 : fix for PHP 5.5 on PmWiki<2.2.103, reported by Johan Bengtsson.
  • 20190707 : fix for PHP 7.2. If you have previously used custom $ThumbList['OrderFunctions'], just rename your ordering function to "cb_tl_{property}" where {property} is the order=property sort keyword. For example, if you had an ordering function like $ThumbList['OrderFunctions']['color'], create a function cb_tl_color($a,$b){ /*here your code*/ }. In case of any difficulties migrating, please contact me.
  • 20150525 : add $ThumbList['disableQVars'].
  • 20150316 : fixes for PHP 5.4 and 5.5. This version requires PmWiki 2.2.58 or newer.
  • 20140825 : add order2 parameter
  • 20130708 : fix metadata extraction when an EXIF question variable was in a thumbgallery caption and not in the captionfmt parameter.
  • 20100315 : fix minor bug with un-purgeable thumbnails, reported by Dan McMullen
  • 20100215 : add ?i question-variable, $ThumbList['Sharpen'], un-purge-able thumbnails (if the thumb filename starts with th---) and fixed a bug with the perpage option for the next to last page. (All suggested by Bang.)
  • 20091212 : allow empty captions after the | in thumbgallery (suggested by Rotuges).
  • 20090831 : fix undefined imcl templates in read mode.
  • 20090817 : minor code refactoring to allow re-processing of some question variables.
  • 20090522 : Added $ThumbList['EnableMessages'], set to 0 to hide supercache messages.
  • 20090415, 20090416 : Allowed for "?x_var" extensible question-variables; added $ThumbList['EXIFvars'] array to enable custom EXIF metadata.
  • 20090413 : Allow for custom metadata functions to override question-variables and set new, longer ones.
  • 20090213 : Fixed broken arrow links in Perpage mode.
  • 20081209 : Added perpage= and perpagenav= parameters, thanks to an idea by Fritz Webering about the handling of supercache.
  • 20081015 : Enabled subtle thumbnail sharpening for installations running on PHP5. Set $HandleAuth "read" levels for actions imgtpl and createthumb.
  • 20080909 : Cleared a number of notices when php is running in error_reporting=ALL (suggested by Dfaure).
  • 20080821 : Added question-variables ?1 to ?4, for the inclusion of captions/titles in Lightbox slideshows.[3] This feature is experimental, and may change when I find a better way to do it.
  • 20080714 : Added height= parameter (suggested by Simon). Fix ImageMagick command line color argument (quotes are required on some systems).
  • 85I (2008-05-18) : Added target= attribute for links, tlmode=-1 and other minor changes [4] suggested by Dfaure.
  • 841 (2008-04-01) : Fixed a problem with the htmlpx=1 setting (thumbnail size was never displayed).
  • 83Q, 83Qb (2008-03-26) : Fixed a security vulnerability (caught by Fritz Webering). All users are urged to upgrade. Added AutoPurge feature.
  • 83A, 83D, 83M (2008-03-10 .. 2008-03-22) : Fixing a bug in Supercache introduced in version 2008-02-08 (reported by Fritz Webering).
  • 2008-02-08 : Fixed a "link" bug introduced in 2008-01-18, when a thumbnail does not exist yet. An ImageTemplate page can now be locally selected in each gallery via a PTV.
  • 2008-01-18 Markup in captions is now enabled for thumb and thumbgallery. See Markup in captions. The $ThumbList['_tmpl'] array entries now cannot contain new lines or leading spaces. Former variables ?N and ?n are now translated to | in a tooltip title and to <br/> in a caption. Minor enhancements of ImageMagick processing.
  • 2007-11-29d : Smarter handling/caching of user-defined sort functions.
  • 2007-11-29 : Fixed bug with $ThumbList['ShowErrors']=1; (behaved like =0); fixed the forced extraction of EXIF data in image templates (the bug existed since the suppression of the exif=1 parameter last week).
  • 2007-11-28 (v43) : Releasing the new Thumblist², after major changes. Feedback is welcome.

The changelog from version 1 up to 2007-11-20 is available at ThumbList-Talk-archive.


See Discussion at ThumbList-Talk.

See Also

  • Mini is a simpler thumbnail gallery for PmWiki, it may be easier to use. It produces square thumbnails.
  • SystemLimits -- If Thumblist seems unable to create a thumbnail, you may need to increase some time and memory limits of the system.
  • Maxi -- An image viewer with inline zoom, suitable for large drawings or panoramas
  • Category.Images for similar recipes.
  • PmWiki.UploadsAdmin, especially the setting $UploadPrefixFmt = '/$Group/$Name'; can be very handy for this recipe (all pictures in a distinct directory).
  • YAG -- "Yet Another Gallery tool" - Create thumbnail gallery of large number of images distributed over multiple pages, not unlike Thumblist with the perpage= parameter.


  • The script was written and is maintained by Petko (5ko [snail] 5ko [period] fr). The first version was loosely modeled after (:attachlist:).
  • If this recipe helps you or saves you time, you can help support its continued development by .


See discussion at ThumbList-Talk


You can edit this page and add your name. Please don't add a vote (+) or (-) if you already added one in the example galleries linked above.

  • I wrote this recipe, but it became too complex, so I now use Mini (more). --Petko January 17, 2010, at 09:48 PM
  • I use this recipe on multiple websites, and I recommend it for its reliability, performance, and comprehensive functionality - meeting a number of different requirements. Yes its complex, but it is well documented and produces great results. --simon January 18, 2010, at 04:23 PM
  • Very smart, very handy. I love it has so many options and can use dedicated template. --gb January 30, 2010, at 04:48 PM
  • (+) Works great. Scott Connard January 31, 2010, at 06:46 AM
  • (+) Great work! han baas Oktober 16, 2010
  • (+) Great job! Thinking about switching to Mini, tho... ccc March 14, 2011
  • (+) Very useful! This recipe replaced two others in my wiki. Good job! - Ian MacGregor August 30, 2012
  • (+) Still like it very much TomG 2012-11-03
  • (+) Works great. Benji January 09, 2014, at 07:09 AM
  • Your name here

User notes +14: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.