This is an advanced topic. If you are new to Piwigo, take the tour before reading this.

What's all this 'metadata' stuff, anyway?

Metadata is information about information. An example would be the album and artist information contained in the ID3 tag of an MP3 song file. In the case of image files, this includes things such as height and width, as well as Exif and IPTC blocks, which are written to a file when a digital camera takes a photo. Also, additional metadata can be written to the image file later in software, such as keywords. Metadata can be useful to the software you use, as well as to humans. Images may contain so called Exif and IPTC tags (one or both). Metadata can be used with many different types of file formats (JPEG, TIFF, RAW etc.). The future of metadata will likely be decided by Metadata Working Group

Basic metadata

Basic metadata are things like filesize, width/height, color depth and sometimes even thumbnails. All images must have this data, and it is needed by browsers and other software to display the image properly. Historically, this data wasn't considered to be metadata, but in reality it is.


Exif (Exchangeable image file format) tags are typically used to describe how a photo was captured. The standard was created by a consortium of Japanese hardware manufacturers. For example, tags can contain information about the model of camera/smartphone used, lens, aperature size, focal length, exposure duration, date/time, GPS coordinates, etc. It could also contain scanner properties. There are many fields defined by the Exif specification, but the ones used in a particular file will vary by the device used. Since it is an open standard, tag usage should be consistent across various software.


IPTC headers are described by the Information Interchange Model (IIM). The header is named after the International Press Telecommunications Council (based in London), who created the standard in the 1990's to make it easier for news agencies to exchange information using computers. Adobe helped to bring this standard to public use. For our images, the IIM serves a purpose different from Exif; It describes the content of the image. Some cameras will allow you to record your name, and other copyright information to a digital photo, using this header. Sometimes, editing software is used to later add information like titles. headlines, captions, descriptions, keywords etc. Again, there are many possible fields described in the standard, and they are readable by most programs.


IPTC and Exif are open standards, but hardware manufacturers have their own secret sauce as well. Cameras will often record some metadata to digital photos which is proprietary, and sometimes device specific. Sometimes it is used by the cameras themselves, and sometimes by image processing software distributed by the companies with their cameras. For example, the Makernotes may include points on an image that the camera used for autofocusing, shutter sync, or noise reduction data. Since this metadata may reveal how a particular device works internally, companies do not publish the specifications to protect their intellectual property (IP). Despite this, many Makernotes have been reverse engineered.

How Piwigo Handles Metadata "Out of the Box"

Piwigo has many ways to display and use metadata, and improvements are sometimes made in updates. Since metadata is stored within each image, it remains intact even if something happens to your Piwigo database.

By default, Piwigo displays some basic metadata on the photo page (dimensions, filesize etc.). When the metadata button is clicked (camera icon with 'i'), some additional Exif metadata will be shown: Camera Make+Model, image capture date+time, and aperature F-number. Piwigo does not display IPTC metadata.

When you import images into Piwigo, the DateTimeOriginal field is extracted from the Exif metadata, and copied into the Piwigo database. It becomes the image's “Created on” property (which is searchable).

Expanding Piwigo's Metadata Capabilities

Note: For some functions, in may be necessary to install Grum Plugin Classes. Also, the metadata available to you depends on the version of PHP your server uses. (Recommended as of Mar-2018: version 5.6)

Firstly, it helps to learn exactly what metadata your images contain, and what Piwigo can access. Fortunately, your standard Piwigo installation already has a tool to inspect some of your Exif and IPTC image metadata. Copy any sample jpeg image to this path: (it must have this file name)

 [your piwigo folder]/tools/sample.jpg

Then, open this link in your browser:

 [your gallery URL]/tools/metadata.php

You should see a page of text that looks like this:

Informations are read from sample.jpg

IPTC Fields in sample.jpg

1#090 = %G
2#000 = 
2#005 = exampledocumenttitle
2#025 = keyword1,keyword2
2#055 = 20170622
2#060 = 100209+0000
2#062 = 20170622
2#063 = 090209+0000
2#080 = mrphotographer
2#105 = exampleheadline
2#120 = exampledescription
2#122 = exampledescriptionauthor

EXIF Fields in sample.jpg

    [FileName] => sample.jpg
    [FileDateTime] => 1503177453

 ( and so on ... ) 

* Note: There is a plugin that makes this even easier: read_metadata

As the output suggests, codes with a # sign are IPTC field labels, the words between square [brackets] are Exif field labels, and the data after them are the corresponding content in your image. These will be important for later.

Changing this Piwigo behavior requires editing the configuration file: [your piwigo folder]/local/config/
Making a mistake here could cause your gallery to become inoperable, so do not modify your files directly. Instead, please refer to the article, The Local Configuration (LocalFiles Editor), about making these changes safely using a plugin.

Showing more metadata


Piwigo already shows Exif metadata (by clicking the “Show file metadata” icon on a photo preview page) by default. You don't need to enable it. The core code that turns this on (or off) looks like this:

$conf['show_exif'] = true;

Some Exif fields are show by default. This is how it is configured in the core code:

$conf['show_exif_fields'] = array(

(to view the core code, click the 'Display reference file: “”' link at the top of the LocalFiles Editor plugin)

To display more Exif fields, all you have to do is add their keys (which you obtained from the tool mentioned in this article) to the array in the plugin. Inserting the example code below into your config plugin, will add a few more camera settings:

$conf['show_exif_fields'] = array(


Piwigo does not display any IPTC metadata by default. To enable it, add this code:

$conf['show_iptc'] = true;

Then you must choose which fields to display. Again, you need key names obtained earlier. Here is an example:

$conf['show_iptc_mapping'] = array(
  'iptc_creator'         => '2#080',
  'iptc_title'           => '2#005',
  'iptc_headline'        => '2#105',
  'iptc_description'     => '2#120',
  'iptc_keywords'        => '2#025',

Using your metadata to make Piwigo more powerful

( Using the LocalFiles Editor)

Using the method above has limitations. 'show_iptc' and 'show_exif' fetch metadata at the time when an image is displayed only. The metadata was not integrated into the Piwigo database, therefore it cannot be used for searching and other functions. For many people, displaying information such as focal length, shutter speed etc. is sufficient. However metadata such as keywords, titles etc. are very useful for other purposes, such as sorting and searching. This section describes how you can get more use from your IPTC metadata by adding it to the Piwigo database.

Copying metadata into the Piwigo database takes place during the synchronisation step. If you added images to Piwigo using the built-in web interface, this should happen automatically for you. However, there are many different ways to add images, and sometimes the Synchronization step is missed. You will then need to perform it manually. (Administration → Tools → Synchronise ] Also, the changes in this section will only affect images that are imported from that point in time forward. To extract metadata from previously imported images, you need to run the synchronisation step.


Piwigo imports some Exif metadata by default. This is enabled by this code variable:

$conf['use_exif'] = true;

Next, the metadata is mapped. A mapping simply matches one key to another. The default code tells Piwigo to set an image's creation date in the database, to the value stored in the 'DateTimeOriginal' field in the Exif metadata.

 $conf['use_exif_mapping'] = array('date_creation' => 'DateTimeOriginal' ); 

This can be expanded by adding more mappings. (again, using Exif fields obtained earlier)

This example maps some comments (Just add this code to local files editor):

$conf['use_exif_mapping'] = array(
  'date_creation'        => 'DateTimeOriginal',
  'comment'              => 'UserComment',

I may sometimes want to sort my photos according to the camera I used. For that we can write code to map the Exif Camera model field to Piwigo's unused 'tags' property. Then we can sort our images using this keyword with the built-in batch manager. Just add this mapping to the array above.

  'tags'                 => 'Model',


Default: Not used.
Enabling variable:

$conf['use_iptc'] = true;

Example of extended mapping which imports IPTC metadata (often added using Adobe Lightroom) into corresponding Piwigo fields:

$conf['use_iptc_mapping'] = array(
  'author'          => '2#080',
  'name'            => '2#005',
  'comment'         => '2#120',
  'keywords'        => '2#025',

* Tip: Using keywords is an excellent way to organise your photos, and even to create SmartAlbums (similar to LR's 'Smart Collection'). Keywords can be used for search filtering in the Batch Manager. If you already use keywords in Lightroom or other photo software suites, this mapping will make your life much easier.


There are limits to the metadata usage in Piwigo. There are only so many image properties in the standard Piwigo database, and core code to use it. You can not map more than one metadata value to one Piwigo property. In other words, we can't use all IPTC or Exif metadata, because there is no place to put it.

Back to top
user_documentation/metadata.txt · Last modified: 2018/03/24 09:20 by plg
github twitter facebook google+ newsletter Donate © 2002-2018 · Contact