Documentation for Confluence 5.8 (Server).
Documentation for Confluence Cloud and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

The Gallery macro displays a collection of thumbnail images in a table, based on the images attached to a Confluence page. When viewing the page, a user can click a thumbnail image to zoom into a screen-sized image and then view the images as a slide show.


  • The images shown in the gallery are taken from the files attached to the Confluence page. You can also specify a different page where the attachments are located. For information about attaching images to a page, see Uploading Files.
  • The captions below the images are drawn from the comments on the attachments. For information about adding comments to attachments, see Uploading Files.
  • By default, the gallery will include all the images attached to the page. You can also exclude or include images using parameters.
  • You can sort your images into a particular order.
  • You can specify a title for the gallery and also configure how many columns you want for the table in which your images are displayed.

Illustration: Live example of the Gallery macro

Using the Gallery macro

To insert the Gallery macro onto a page:

  1. In the Confluence editor, choose Insert > Other Macros
  2. Find and select the required macro

Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of suggested macros. Details are in Using Autocomplete.

To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open, where you can edit the parameters of the macro.


Parameters are options that you can set to control the content or format of the macro output. Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).  

The full list of parameters is shown in the following table. If the name of an attached file or page contains a comma, you can refer to it in the relevant parameters below by enclosing it in single or double quotes, for example "this,that.jpg", theother.png




Gallery Title


Specify a title for your gallery.

Number of Columns


Specify the number of columns for your table.

Images to Exclude

No exclusions. Include all the pictures on the page.

The gallery will ignore any pictures specified. You can specify more than one picture, separated by commas.
Note: The filename and filetype for this parameter are case-sensitive. For example, 'my picture.PNG' will not be recognised as 'my picture.png'.

Include these Images Only

Include all the pictures on the page.

If you specifically include one or more pictures, the gallery will show only those pictures. You can specify more than one picture, separated by commas.
Note: The filename and filetype for this parameter are case-sensitive. For example, 'my picture.PNG' will not be recognised as 'my picture.png'.

Exclude Images with these Labels

No exclusions. Include all the pictures on the page.

The gallery will ignore any pictures that have the specified label. You can specify more than one label, separated by commas. For information on labelling the attachments, see Add, Remove and Search for Labels.
Include Images with these Labels Only
None. The images are not filtered by label.Filters the images to display, based on a list of labels. If you wish to enter more than one label, separate the labels with commas. Confluence will show only images that have all the labels specified. (The match is an AND, not an OR.) For information on labelling the attachments, see Add, Remove and Search for Labels.

Use Images in these Pages

If no page is specified, the gallery macro displays the images attached to the page on which the macro is used.

Specify the title of the page which contains the images you want displayed. You can specify more than one page name, separated by commas. To specify a page in a different space, use the following syntax: SPACEKEY:Page Title

Sort Images By

None. The sort order is unspecified and therefore unpredictable.

Specify an attribute to sort the images by. Sort order is ascending, unless you select the Reverse Sort parameter (see below). Options are:

  • name – file name.
  • comment – comment linked to the attached file.
  • date – date/time last modified.
  • size – size of the attached file.

Reverse Sort

Off. Sort order is ascending

Used in combination with the Sort Images By parameter above. Use Reverse Sort to reverse the sort order, from ascending to descending.

Available values in storage format and wikimarkup:

  • true – Sort order is descending.
  • false – Sort order is ascending.

Image file formats

You can attach image files of any format to a page. Confluence supports the following image formats in the Gallery macro and when displaying an image on a page:

  • gif
  • jpeg
  • png
  • bmp (depending on browser support)


Code examples

The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page. 

Macro name: gallery

Macro body: None.

Storage format example

Wiki markup example




  1. Some users are complaining that the images are too small (after clicking on the thumbnail). We posted some wireframes with text on them and since the gallery seems to be resolution and browser size specific, they can no longer read it. Is there a setting to either change it back to a pop-up or force it to render at 100% of the image size?

    1. Hi Ben,

      Confluence actually allows you to limit the maximum size of a single file attachment. The detailed doc is available at:

      If you have further questions, please feel free to raise a support ticket at


      1. I think Ben was referring to image dimensions, not physical file size.  I have the same problem - we added some images to the gallery, and when viewed with a slideshow, the text on them is unreadable.  It would be nice to have configurable image size when viewed either within a gallery or in the slideshow mode.  In addition, would it be possible to (optionally) include a link to the original while viewing the gallery?  This way if an image is too small to see, a user can click on it and view the original file in the new browser window.

        1. Hi guys,

          Apologies for any confusion caused here. I guess this problem can be resolved if this feature request can be turned into reality: CONF-6222 (wink)

          Don't forget to cast your vote!


  2. Is there an option for displaying the file name under the picture instead of the just the Comment?

    1. Hi Tomi, I am afraid that this feature is not available. If you are keen on it, feel free to raise it in


      1. Add your votes here so Attlasian add this feature:

          CONF-13936 - Add parameters for displaying the file name and/or the comment under the picture as well as the file size Open

  3. Is there any way to force a redraw of the thumbnails used in the gallery? When uploading a new version of an image, the thumbnail will show the old version.

    If the two images are different aspect ratios, it does this crazy thing where it's the old image with the new image's proportions.

    Only seems to happen with uplaoding new versions of an image using the same filename.  Our current workaround is to rename each offending file from "filename.jpg" to "filename_a.jpg" or something like that, so that the system uses it as a "new" image.  This is however somewhat tedious with large sets of images.


    1. Hi William,

      I am afraid that this problem is due to your browser cache rather than Confluence. What I would suggest is try holding the shift key and click on the refresh button for your page.If this didn't help I suggest you to raise a support request on this issue at


      1. Anonymous

        I have been having this problem too. It is not a cache error though, because I deleted my cache and the pictures did not change at all. Do you have any other ideas why this may be happening?

  4. i think i have done everything correctly but it doesnt seem to resort.

    i couldnt attach images to this wiki so i uploaded to a another server to help clarify what i am doing

    any help is much appreciated

    1. Hi David,

      I could not replicate your problem, I would recommend you to raise a support ticket in our Atlassian support system:

      By raising a support ticket, this may speed up the process to overcome this issue. Also, please attach your instance's
      application server log and atlassian-confluence.log.

    2. Anonymous

      Confirmed. I'm using Confluence 3.0.0_01.  Within Edit Gallery Macro, if I choose the Reverse Sort checkbox, the resulting macro includes reverseSort=true. This will not reverse sort the gallery.  If I manually change the macro to be reverseSort instead, then the gallery will indeed reverse sort.

      1. Hi,

        I have raised a bug report here. I would suggest you to add yourself as a watcher for the mentioned bug report and feel free to comment or address your concerns through it.For further details on how we include new features and improvements, you might want to read this page


  5. I am creating an employee directory and I want the thumbnail to link to a personal space.  Any chance? (smile)

    1. Hi Philip,

      As far as I know, you can try this method:

      !apple1.jpg! is the attachment image in a page
      try = Space key of a space
      Home = Page title

      For more in formation on linking please refer to this documentation:

      Hope that helps.
      Best rgds,

  6. Anonymous

    we using the "old" 2.10.2 confluence wiki-software. When I try to use the gallery macro with 165 pictures, none of them are displayed.
    I don't know what can be wrong. These pictures are all fine (.jpg and .JPG).

    Any ideas? Thank you very much!

    1. Hi, there. In case this problem remains unresolved, please feel free to raise a support ticket with some sample images and the wiki markup.

  7. I'd like to create a gallery that pulls all pictures from a particular space.
    I've tried:

    where LPC=current spacekey
    And also:

    Any help would be greatly appreciated...!

    1. Hi Meredith,

      Currently, the gallery macro is only able to pull all pictures from a particular page.
      If all your pictures are stored in a particular page in the space, you can use the following code:

      However, if your requirement is to pull all images in the space, I am sorry to inform that this feature is not available in Confluence yet.
      Feel free to raise for a feature request in

  8. I get this error:

    "Error trying to draw image gallery org.apache.velocity.exception.ParseErrorException: Encountered "=" at /templates/gallery-dynamic-slideshow.vm[line 64, column 37] Was expecting one of: ... "-" ... "+" ... "*" ... "/" ... "%" ... ... ... ... ... ... ... ... ... "

    Any ideas why?


    1. Hi Corey,

      I tried to find for the above error message in our issue tracker and found out some similar issue. I think you should take a look at the following bug report and try out the suggestion mentioned in it:

      Basically, I think you have two versions of the gallery plugin installed. One that you installed manually and another that comes bundled with Confluence. If this is true, kindly disable the one that you have installed manually. If this is not true, then one of the workaround mentioned in the aforementioned bug report might be of help.

      If this does not solve your issue, kindly raise a support ticket at, so that your issue can be further investigated. Also provide the following:

      1. The exact error that you receive when using the macro
      2. A copy of your Confluence log file located at <confluence-home>/logs/atlassian-confluence.log
      3. The system information page. You can obtain the page by accessing the http://<path-to-confluence>/500page.jsp
      4. Screenshots that illustrates the problem.


  9. Anonymous

    When I click on an image in the gallery, a new browser window opens, then a dialog box appears asking if I want to open or save the image (standard download dialog box for IE 7). The full screen image and slideshow options don't work.


    1. Hi, there. I have a few suggestions:

      • Check whether you have the legacy Gallery Plugin installed. If so, please disable the plugin
      • Try using other browsers to confirm if it is an IE-only problem.
      • Try clearing out the IE cache. You might as well want to force refresh the browser cache by pressing CTRL+F5 on that page
      • What is the wiki markup? What is the type of the images? Does this problem happens to other images?

      Hope that would be a good start.


  10. Anonymous

    Is t here a way to make a slide show as you would typically see on a Web page. That is, you see one photo, and you can click on that and see the others one by one. The gallery feature is useful. But I would prefer to have only one photo showing on the page, not all of those in the gallery. Thank you.

  11. The gallery generation is horribly slow now after 3.0.

    We used to use the old gallery plugin (which is now uninstalled). This worked fairly fast and ok. After the update it seems that the gallery creation is causing an excessive delay (>30 sec.) and makes it practically unusable. I've meanwhile removed the gallery macro from the most frequented pages to make those pages accessible again.

    Is this a known issue? Any workaround to speed things up?

    1. Hi Thoralf,

      In order for us to investigate on this issue further, could you please raise a support ticket to Also provide the following information in the support ticket:

      1. Number of images that are being used in the page.
      2. A sample page with all the images attached to the ticket.
      3. Rotate confluence log file. Restart Confluence instance. Enable Page Request Profiling. Reproduce the issue.
      4. A copy of your latest Confluence log file located at <confluence-home>/logs/atlassian-confluence.log
      5. The system information page. You can obtain the page by accessing the http://<path-to-confluence>/500page.jsp


  12. I attached a bunch of PNG icons to an 'icons' page in my wiki so I could make them easily accessible to the 'lozenge' macro.  Two issues:

    1. The background of the icons was probably transparent.  It renders in black in the gallery, which is kind of ugly.
    2. There's no way to see the filename easily.  It would be nice to have an option, showfilename=true, that would enable this behaviour.
    1. Hi Brian,

      The background of the icons was probably transparent. It renders in black in the gallery, which is kind of ugly.

      I afraid this is a known issue. There is an bug report on this issue:

      Please add your comments to the discussion and add yourself as a watcher for future updates. Also, please bear in mind the following document on how we schedule features for inclusion in our products: How we approach fixing bugs.

      There's no way to see the filename easily. It would be nice to have an option, showfilename=true, that would enable this behaviour.

      You might want to raise an improvement request in JIRA:

      Hope that helps,
      Best rgds

    2. Anonymous

      Found the following feature request for allowing for the display of filenames in the gallery plugin

  13. I have a page with five attachments on it. All of them are JPEGs, with file names ending in .jpg. All of them have MIME types set to image/jpeg. All five of them were uploaded at the same time, using the API.

    The page includes the {gallery} macro with no arguments. Three of the attachments display in the gallery, but the remaining two do not.

    The only obvious distinction is that the two attachments that don't display are larger than the other three; they're both over 1.5 MB in size.

    Any thoughts/things to look for?

    1. Answer: the gallery macro does not support progressive JPEGs. There's a bug for this, without a fix date. I'd suggest that this limitation be documented on this page.

  14. Anonymous

    Hi, how can I insert text under the pictures? In the example above, under the office photo it says "Here's an office photo", not sure how to do that.


    1. The text shown is the comment for the attachment. You can enter a comment when uploading an attachment, or by editing an existing attachment.

  15. Anonymous


    I am trying to  create a Gallery with a slideshow mode. For some reason it doesn't work. On click it only opens up in a new window. Any idea why it doesn't work?? I did work once, the very first time. Then it stopped working.



    1. Hi,

      I am trying to create a Gallery with a slideshow mode. For some reason it doesn't work. On click it only opens up in a new window. Any idea why it doesn't work?? I did work once, the very first time. Then it stopped working.

      I have once experience that user have two Gallery plugin that cause the problem. You might want to check if your instance is having two Gallery module. You can check this through 500page.jsp or in the plugin manager via Confluece Admin >> plugin

      Hope that helps.
      Best rgds,

  16. Anonymous


    I am having problems with Gallery -macro. Confluence 3.0.2 gives me the following error - Unknown macro:

    . We had gallery plugin in previous version of Confluence but I uninstalled that.

    Can anyone help, please? Thanks in advance.

    1. Hi,
      The Gallery macro should come with Confluence 3.0.2. Could you please double check if this macro has been disabled in your Confluence instance via Confluence Admin page > Plugin > Advanced Macros > Gallery. If it is disabled, please try to enable it and try again.

      Hope it helps.


  17. mw

    Here are two feature requests for the Gallery macro:

    1. How about losing the "fade to white" transition and just doing a straight crossfade to the next image? White isn't always desirable.

    2. How about allowing users to hide specific thumbnails in the gallery, but still have them appear in the slideshow? For example,what if I'd like the macro to act like a traditional slideshow where there's only ONE thumbnail: the first image. All others are hidden in the Gallery, but subsequently appear in the slideshow. This would give users the option to use the macro to create a full gallery of images OR a PowerPoint-style slideshow presentation. Verrrrrrrrry useful!

    1. Hi Mw,

      I have created two improvement requests as per your requirements:

      1. ADVMACROS-151
      2. ADVMACROS-152

      Please add yourself as a watcher, vote for these improvement requests and add your own comments to these requests. For further details on how we include new features and improvements, you might want to read this page


      1. Anonymous

        Hallo! When will the second point be done? Should not be too complicated to implement..

        would be really helpful!

  18. Anonymous

    Is it possible to include a url as a hyperlink in the image comment? It seems markup is not processed from the image comment, but this would be very useful to me.

    1. Hi

      I am afraid that this is not currently possible. Feel free to raise an improvement request at and describe in detail how you require this improvement to work. Please add yourself as a watcher, vote for this request and add your own comments to this improvement request. For further details on how we include new features and improvements, you might want to read this page


  19. Anonymous


    Are there any plans to add a rating functionality to gallery images?

    Thanks in advance for your reply.



    1. Hi Rich,

      I would strongly recommend you to raise a feature request in JIRA:

      Also, there is also few third party plugin which might be able to satisfied your requirement:


  20. Anonymous

    Hi curious if there is a way to put a max image limit to the gallery.

    I want to keep uploading 3 slides to attachments, but only have current 2 or 3 images uploaded viewed instead of all of them.


    1. Anonymous

      sorry example


    2. Anonymous

      +1 to this request.  Please open a ticket on it or whatever. I came here looking for this feature.  Now I have to move my images to a holding page and manage the qty.... icky workaround.

  21. Anonymous

    Can the images in the gallery be used as links ?

  22. Anonymous

    I've attached images to a page and added them to the gallery macro, but I keep getting an error saying: "There are no images attached to this page."

    Here's the code:


    1. Hello there,

      It looks like you might be using the parameters (which are described above) incorrectly.

      You need to specify the page (in your Confluence site) to which your image is attached (using the page parameter) and then use the include parameter to specify the file name of the image attached to that page.

      Hence, an example of what your code might look like is:

      • {gallery:title=Test|columns=1|page=MYSPACEKEY:Page Containing Attachment|include=ChrInjuryStates_Design.jpg}

      Where ChrInjuryStates_Design.jpg is the file name of the image attached to a page called Page Containing Attachment in the MYSPACEKEY space of your Confluence site.

      (If no page parameter is specified, the gallery macro looks for images attached to the page on which the macro is used. If it can't find any, you'll get that error message.)


  23. Hi there,

    I've got a problem with the gallery Macro. When I click on a picture the slideshow doesn't start. I just see a transparent gray screen without a picture.

    Can anyone help me?


    Kind Regards


    1. Hi Christoph,

      To further investigate on this, I would suggest you to raise a support ticket under Confluence project in:

      At least, a Confluence support engineer could help you to look into your problem.


    2. We have the same problem.  Did you ever raise a support issue on this?  If so, was Atlassian able to resolve it?  And, are you willing to share whatever fix they did, with us?  If you never raised a support issue, then I'll go ahead and do it, I just don't want to duplicate things if I don't have to.



  24. Is it expected behaviour for the title of the gallery to show up in the toc ? I think it shouldn't, or if it does, it should be clickable.

  25. Is there a way to set the column width for the gallery macro? I have some narrow images that look all scrunched together in the gallery format. Since the column attribute is already set (column=n), it would be great to set a percentage or value for each column.

  26. Is there a way to make seperate galleries on one page easier to use?

    Currently our artists have to type individual filenames to create each gallery which is very fiddly and takes a lot of time to do for several galleries of up to 20 images on the one page. 

    We have thought of just adding the images as separate pictures and using the 'resize and link to image' functionality to resemble a gallery, but then we cannot scroll through which is very frustrating to people reviewing the images. 

  27. Hi all,

    is there any way to define to size of a picture appearing in the gallery?

    By now our pictures in the gallery have the same size as in the slideshow...

  28. Anonymous

    Is it posible to change the size of the thumbnail used in the gallery?

    We are using version 4.3.


  29. Anonymous

    Hi all,

    Im using confluence 3.2 and I want to attach 20 images at the same time to make a gallery macro. However, it just allows me to upload 1, can I upload several images there? I already tried the the drag and drag function but is not working. Then I read the support and it says that i might need to install Gears–> I go to install it and google says that that feature was replaced by HTML 5... I´m very confused. Do you guys have an idea about how could i do that?




  30. A cool feature that I would use would be to be able to add a link to each image that takes you to the place in the document where that image occurs. I.e., instead of showing a larger image when you click it, link to the place in the document where the image occurs. A place we are using this right now is in our company directory where every employee has a picture next to their information. Being able to click on a picture and link to the employee details would be very nice.

  31. I want to set up a gallery of artwork and add a label to each image attachment with the artist's name. How can I then display the list of attachment labels on a page so a user can click on an artist name and see all their images? It seems that the standard label macros don't include attachment labels.

  32. Anonymous

    The documentation for "Include images with these labels only" says "Confluence will show only images that have all the labels specified. (The match is an AND, not an OR.)" The behavior I'm observing is that it's actually an OR relationship between galleries and labels. I have to add labels in the "Exclude" field to remove images with labels I don't want to appear in the gallery. It would be nice if there was some syntax like && or || in these fields to allow for more flexibility.

  33. Hi everyone!

    I was wondering if someone can help me with a simple problem. When I used the gallery macro, my vertical images were automatically flipped horizontally to align with the other horizontal images. I can't seem to find where to flip the images back. I checked to make sure the images I uploaded as attachments were uploaded in the correct orientation, and they are, but they seem to be automatically adjusted to align horizontally when called to appear in the gallery macro. 


  34. Anonymous

    Hello, I am having the same problem as Nicole Choy. Does anyone have any suggestions on how to fix it? The example on this page seems to be able to display a vertical image (Waterfall photo) just fine. 


  35. Anonymous

    how can I delete a picture from a gallery?

  36. Hi, I'm having a problem after migrating to OnDemand: the thumbnails in my Gallery are very low quality.

    Here's my original Gallery (Confluence 5.3): 

    Here's the OnDemand version:

    I tried adding new image attachments to OnDemand, but the result was the same. The images are in PNG format.

  37. What about SVG support ?

  38. As for the documentation: Are you sure that the filter is a logical "AND"? I think it's an "OR".

    However, feature request: Why can't this be configured?

  39. Hi.

    Is there a way to delete images from a gallery once it is created in Confluence.

    I cant seem to work out how to do this.

    1. Hi Ryan,  the gallery macro displays images that are attached to Confluence pages. Remove the attachment from the page (you'll need the Delete attachments permission in the space) and it will no longer appear in the gallery. 

  40. I have a parent page title with a colon in it (e.g. "12345: Some Title") and a bunch of child pages underneath. I want to be able to use the parent page's attachments in the galleries I build on the child pages. Since the way linking to pages in different spaces uses the synatax, "SITEKEY:Page Title" how would I link to a parent page with my title structure?

    1. Hi Kunal, Colons and other special characters in page titles can be quite problematic for simple macro parameters to handle - you are correct that Confluence will interpret the colon in the page title as indicating a space key.  

      I've just tried it out, and if you actually include the space key before your page name it should work fine  (for example  MYSPACE:Page title: with a colon). 

      1. Hi Rachel, Thanks! I had tried that earlier, but forgot that the Sitekey was one word. Works now that I've swapped it.

  41. Hi, just seeking clarification on one aspect of the Gallery macro. The documentation refers to it showing a 'thumbnail' of the image - but when I have used the gallery macro with attached images (not images inserted and set to thumbnail) they are not displaying as thumbnails and I can't see a way of setting a size. So I end up with a gallery which uses up a lot of page space tot he point where it impinges on the layout. Any suggestions? thank you

  42. HP

    Is there any limitation on number of attachment on a page? Thanks!

    1. Hi HP,

      I can say I've tested this with a 'large number' of images, and there seems to be no limit. If you hit a limit, let us know! (wink)