Documentation for Confluence 5.4.
Documentation for Confluence OnDemand and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

An attachment is any file that is included with your page. Examples of attachments are screenshots, photographs, other images, Word documents, presentations, PDF documents, videos and sound files. Attachments are useful when you want to share information that exists in another file format.

You can display a list of attachments on your page – these may be the files that are attached to the current page or to any page in the space. Use the 

  • Use the Attachments macro to show a list of the attachments on the current page, or 
  • Use the Space Attachments macro to show a list of the attachments in the current space. 

Both these macros generate a table of attachments which is clickable.

Using the macros

To add the Attachments or Space Attachments macro to 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.

On this page:

Parameters of the Attachments 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).




Filename Patterns


A comma-separated list of regular expressions, used to filter the attachments by file name. Note that the parameter values must be regular expressions. For example:

  • To match a file suffix of 'jpg', use .*jpg (not *.jpg).
  • To match file names ending in 'jpg' or 'png', use .*jpg,.*png

Attachment Labels(none)A list of labels, used to filter the attachments to display. If you wish to enter more than one label, separate the labels with commas. Confluence will show only attachments that have all the labels specified. (The match is an AND, not an OR.) For information on labelling the attachments, see Adding Labels.

Include Old Attachment Versions


A value of true will include previous attachment versions in the list.

Sort By


The sort order for attachments. Note that people viewing the page can change the sort order by clicking the column headings. Valid values are:

  • date – sorts by reverse chronological order (newest first)
  • size – sorts largest to smallest
  • name – sorts alphabetically
Sort OrderascendingUsed in combination with the Sort By parameter, to sort the attachments in ascending or descending order.

Allow Upload


If selected, the list of attachments will include options allowing users to browse for, and attach, new files.

Page Title(none)Used to display attachments from another page. If you do not enter a page title, the macro will display the files attached to the current page.


Viewing files and changing file properties via the Attachments macro

The list of files displayed by the Attachments macro can be expanded to show options for viewing the files and other actions, provided you have the relevant permissions.

  • If you have specified the 'Allow Upload' parameter, users will be able to upload attachments directly from the list.
  • You can delete attachments. Note that you can only delete the entire attachment (including all versions). To delete a specific version of an attachment, you must go to the 'Attachments' view. See Deleting an Attachment.
  • You can edit attachment properties and labels. If an attachment is an Office or PDF file, they will see the appropriate options for Office Connector files.

Screenshot: The Attachments macro, showing details of an attachment

Parameters of the Space Attachments macro

The Space Attachments macro displays a list of all the attachments in a space. You can choose to show attachments from the current space, or another space. 

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).

Space(none)Selects the Confluence space to display attachments for. If you do not specify a space, the current space will be used.
Show Filter ControlstrueDetermines whether or not the filter panel is shown. If you select this option, people viewing the page will be able to filter the list of attachments by file type (extension) and by label.


Screenshot: The Space Attachments macro


  • No labels


  1. In addition to selecting which columns to display, I would like to customize the titles of the columns.  Is that possible?

    1. Hi Carol,

      This is not something that Confluence provides out-of-the-box. If you'd like to pursue other options, could I suggest that you try Atlassian Answers, or contact Technical Support at ?


  2. Anonymous

    I wish we could customize the columns. That would make it a whole lot easier


    dual action cleanse

    1. See here for custom attachment display.

  3. It would be a nice feature if we could customize the fields that are available for attachments.  For example, if I wish to add a field name "Project Manager" to an attachment.

  4. Nice feature, but I am getting an additional link at the bottom of the page saying "OPEN WEB FOLDER" which will lead to a 404. Any idea what this link is supposed to be for?

    1. Hi Frank,

      The link is supposed to be used in conjunction with WebDAV Plugin. It is meant to allow you to open a local directory containing the attachments. However, it is also known that users who do not use this plugin will still be presented with this link. There is a bug report, being tracked at:

      Please add your comments or be watcher to keep yourself updated on the issue. Hope this helps.


  5. Hi ,

    I am encountering an issue with attachments whereby when one uses the Attachments macro on a page it works fine but the same is not so for a template 

    It gives an error msg:Error formating macro :attachments:java.lang.NullPointerException

    Is this a bug ? All the other basic macros like tip, info works fine on templates

    Confluence version: 2.4.3



    1. Hi Gerin,

      To my understanding, the error message is thrown because attachment objects are not available in the template page. In a normal page, attachment objects are available and accessible by the macro, hence there is no error. However, I have tested this in Confluence 2.9. The error message will not be displayed when you view the template page, but it will appear in the template preview. Hope this helps.


      1. Gerin Abraham and Azwandi Mohd Aris [Atlassian],

        I'm running up against this in my template creation. I have an Attachment macro in my page template. I want the Attachment macro on the final page, but don't want users to have to attach a file while going through the Page Template Wizard. I'm using Confluence OnDemand. There are a few links that seem to relate to this issue, but none that seem to resolve it for OnDemand.


        1. Hi Chris, this problem is still not fixed as per The workaround to use user macro is not applicable to Atlassian OnDemand as user macros are not allowed in the platform per Restricted Functions in Atlassian OnDemand.

  6. I was looking for a way to reverse the sort order,and the
    reverse=true parameter, as used in eg. the blog-posts macro, appears to work.
    Is this intended/reliable behavior? If so, you may want to add it to the documentation.

    edit to add : on closer inspection, the reverse=true doesn't seem to affect anything, it's just that the default sort order of the sortBy=date parameter apear to be reverse, ie. newest first.

    whatever the intended behavior is meant to be, it probably should be documented.

    also, the reverse paramater would be a handy thing to have, doesn't seem to be too difficult given it's presence in other macros.

    1. Hi Tony,

      Thanks for the notification.

      The feature requested is not available yet. However, there is a a improvement report being raised in JIRA:

      Feel free to add your comment, vote for it and add yourself as a watcher for future updates. Also, I have created a task for our technical writer to review this issue.

      Hope that helps.
      Best rgds,

  7. Hi there,

    I can't get the "Comment" field to wrap.. Long comments make for a very broken page!!

    Any help would be greatly appreciated.. Thanks!


    1. Anonymous

      Me too. This is very annoying because users are not putting comments on the attachments to stop the page getting too wide. Is this issue being looked at?

      1. Hi there,

        I have added a tentative workaround in the following report:

        Hope that helps,

  8. Anonymous

    this patterns parameter doesn't seem to match the filename. or at least the regex engine is not behaving as expected.

    if i had a file called "The Quick Brown Fox.doc" you would think "patterns=\bFox\b" or even just "Fox" would match, but it doesn't. what is the trick to matching on the name of a file rather than just a list of extensions?

    1. Hi,

      Based on your description, I have found a similar bug report raised previously. Here is the bug report raised on this issue:

      I would suggest you to add yourself as a watcher for the aforementioned bug report and feel free to comment or address your concerns through it.


  9. Anonymous

    When viewing text attachments, they do not display with any line wrapping and thus can give a very wide horizontal scrollbar for the browser.  Is there a way to get text attachments to have a width based on the browser width and then line wrap within that width?


    1. Hi,

      I have a mere suggestion, instead of making the table to have the wrap ability and specify the width. You might want to try to make the Attachments macro to have scrollbar if the attachment description is too long. I have created an example shown below. Hopefully you will be able to have better understanding on this. Please follow the steps shown below:

      1. Enable the html macro via Plugin manager
      2. Now paste the following code to the page:
      3. Save the changes.

      Hope that helps,
      Best rgds

      1. Hello!

        Thank you for this explanation. But is there a way not doing this with html, as this macro is deactivated in our organization on purpose...

        Thx, BR Stefan

        1. If you are allowed to change the page layout of the space, you can overwrite the CSS white-space declaration for the attachments table. Just put the following lines before the line <div class="wiki-content">. It doesn't look perfect but it does the job:

          As David Peterson pointed out above you can also use the Reporting Plugin to built your own attachments table:

          This is very flexible and you can also create a shortcut by defining a user macro.

  10. kaz

    Hi all,

    I am trying to display a couple of lists of page attachments, limited to files with names that contain particular strings. Here is the macro I've tried, with criteria for the file name contents....

    Files with "fredjones" in them

    (open curly bracket)attachments:patterns=.*fredjones|sortBy=name(closed curly bracket)

    Files with "fredsmith" in them

    (open curly bracket)attachments:patterns=.*fredsmith|sortBy=name(closed curly bracket)

    Unfortunately, this results in the text "No attachments on this page" being displayed, despite there being files with "fredjones" and "fredsmith" in the file names.

    Am I correct to assume that the patterns criteria is based on file extension, not file name? If so, what can I use to filter the files by what is in the text of the name, before the extension? 



    1. Hi Kazb,

      I am not sure if I got you correctly.

      If so, what can I use to filter the files by what is in the text of the name, before the extension?

      You want to filter a list of attachment depending on the file name and extension? If yes, you can try this code

      NOTE: You might want to change <attachment name> and <extension> to the desire file name and extension.

      Am I correct to assume that the patterns criteria is based on file extension, not file name?

      Yes by using the following syntax:

      That pattern which is define is to search for the *.fredsmith extention

      Hope that helps,
      Best rgds

      1. kaz

        Thanks Zed, when you first posted this, I thought it worked... but today again I am trying to apply a filter so that my attachments only include files with the word "agenda" in them... and ".*agenda" just simply doesn't work.

        Like Anonymous below, I still need an answer here!

        This has nothing to do with the file extension... just the contents of the file name.


      2. Anonymous

        Is there a way to filter the list using the filename? Not the file extension?

        For example, if I want only files (attached to the page) that start with the letter A, using the following syntax doesn't work.


        1. Hi all,

          Is there a way to filter the list using the filename? Not the file extension?

          Yes, I believe you can archive your requirement. I have created a macro below to only filter the attachment which starts with the letter a:

          Please give the above macro a try.

          Hope that helps.
          Best rgds,

          1. Hi,

            your macro filters only filenames which start with "a". How can I match the middle of any filename, e. g. with several files like this:







            How can I display just files from version 1_7 and below another macro with just files from version 1_6?



            1. try patterns=.*1_7.*

              but i don't know if "_" is a special caracter..

              i tri this with .*ITA.* for filenames that contain "ITA" and it works..

  11. Can I specify that I want the attachments of a specific page?

    This would allow me to create a number of different pages with a dozen attachments each, then have a master page with expand macros on titles that open the table of attachments of a given page when the user clicks on them. Something like this:

     Stuff about A

    Table of attachments appears here

     Stuff about B

    Table of attachments appears here


    1. There is no macro parameter to cater for this requirement. However, you can include or excerpt-include page A and page B. For instance, in page A and page B:

      Some contents

      In the main page:

      {excerpt-include:page A}
      {excerpt-include:page B}

      Hope this helps!

  12. I think it would be *really* helpful if this macro allowed for a simple listing, like allowing you to somehow specify that you just want the filename to show.  Maybe add an attribute "columns=filename,size,etc" or a "simple=true".

    1. Hi David,
      I agree with you that would be a nice feature. As far as I understand, this feature is not available yet. Please feel free to make a feature request under Confluence project at is where our programmers keep track of the bugs, task, feature & improvement request, etc. Please share your comment by creating a new issue, vote on it, and add yourself as a watcher for future update.

      Thanks & regards,

  13. Anonymous

    Why is the name column of the attachments macro so small, and the comment column soo big?

    Where can this be modified? It doesn't seem to work with changing the css.


  14. I have that problem too... 

  15. I have a problem with the column headings of the attachments macro. For example instead of "name" it shows this "/display/testDemonstration+Office+Anbingung?sortBy=name" as a link.

    Does anyone know how I coud fix this?


    1. Hi Sabine,

      I would highly suggest you to raise a support ticket to for this problem so that the issue can be further investigated. Also provide the following:.

      1. Have you customised the confluence-attachments-plugin-x.xx.jar prior to this problem?
      2. Have you customised Confluence in any way?
      3. A copy of your Confluence log file located at <confluence-home>/logs/atlassian-confluence.log
      4. The system information page. You can obtain the page by accessing the http://<path-to-confluence>/500page.jsp
      5. Screenshots that illustrate the problem.


    2. I get the same thing. 


      Not pretty.

      Did you get a solution?

      Thank you.

      Rudy Bake

      1. I didn't get a sulution, but somehow the problem is gone. I think a restart did it, but I don't know for sure because I was working on a different issue when I noticed that everything was fine again.

  16. I had this in Confluence 3.1

    After a re-index and restart, it was gone. Now upgraded to 3.1.2 and I don't have the problem anymore.

    However, I am still looking for an easy way to adjust the column sizes....

    The comment column is so big, while the name is too small. Anyone has suggestions?

  17. Anonymous

    regular expressions don't seem to work in attachment macro.  the pipe for or and the parenthesies for groupings are both part of macro syntax and throw an error when you attempt to put them in regular expression, even if you escape them.  Is there documentation anywhere on regular expressions as modified for use in the attachments macro attribute for confluence?

    1. Anonymous

      I have run into the same problem.  The solution I have found is as follows...

      I have attachments named:




      I want to show them as 14 separate lists of XYZ.01 thru XYZ.14

      I also want a 15th list of all files that are not in the first 14 lists.  Here's how I do it...  for the 14 lists, I use:




      for the 15th list:


      Its messy as hell, but it works.

  18. Anonymous


    how do I use a logical or within the regular expression?

    I have got 2 files, anywhere.tif and everything.pdf, and I want to display them both.

    I tried

    Error rendering macro 'attachments' : Unclosed group near index 6 .*(any ^

    but it doesnt work in Confluence.

    Kind Regards


    1. Anonymous

      Sorry I didnt use the code-statment in my posting before

      1. Hi,

        If you want to display all of the attachment on the particular page, this simple macro will do the trick:

        If you want to display both of the file you mention, you could do that by pointing their file type. This simple macro will do the trick

        I hope this trick would help you.

        Septa Cahyadiputra

  19. Hi,..

    is there any way to configure the columns of the list view of attachments?!

    In any earlier version of confluence or the attachments-plugin, the 'edit in office' link was shown regularly and now it is 'hide' within in the options-menu of this tiny settings-icon on the right side...

    For me this is fine but I have several hundrets of users, who does not really understand to find this function there...

    Would be great if there is any solution for that?!

    Thanks and regards


  20. Anonymous


    the attachment macro opens the attachment in the current window, when you click on the attachment to open it. Is it possible to open the attachemnt in a new tab, rather than the current one?

    Thank you in advance

  21. Anonymous



    Is there anyway to make the width of the Name column wider so that more of the file name is displayed? We have a lot of files with long titles that are always cut off, which makes it hard to know what file you are opening. I tried to use come custom CSS on the table, but it only increases the Table Header width, and not the width of the rows where the name is stored.


    Any ideas?



    1. Hi,

      even if you would be able to increase the width with css alone, it won't help you in this case, as the macro already shortens the name of the file in the html content. You probably would have to change a bit of the coding of the bundled attachments macro, but with a macro that important to the core I'd probably stay away from doing that.

      Maybe there's a plugin vendor out there who already did this.

  22. Anonymous

    I have tried unsuccessfully to see where I can configure which columns/fields are shown in the Attachment macro output yet the examples above seem to show very distinct layouts. By default I get the layout I required in 4.3 but in 5.1 I get a very simplistic view and no obvious way to restore fields such as Size, Creator, Creation Date .... which are all missing from my table. 

    1. Anonymous

      Sorry - didn't finish the message ... 

      Can you please point me in the direction of where I can find out how to restore my preferred view?


  23. Anonymous

    hi, is there any code to automatically get the attached file name and plug it into viewfile macro. Ex: 

    Error rendering macro 'viewfile' : The viewfile macro is unable to locate the attachment "$attachment.filename" on this page



  24. Anonymous


    Does anyone encountered Old Version not displaying even after "Include Old Attachment Versions" was ticked? I don't think its a Macro issue because the olde version is displayed when in the Attachment page.

    Thanks in advance.

  25. I would like to see the option for "expanded = true" or something along those lines, so that all attachments are expanded by default. Also, we should have a link available for "Expand All" and "Collapse All"


  26. Anonymous



    I am trying to use the space attachments macro to display certain attachmentsonly, but I do not have the attachment labels parameter in the macro set up as shown above. Version is 4.2.3 if that may be the cause, or am i missing something else?


    Thank you for any advice


  27. Each attachment in the Attachments list macro has a corresponding "Comment" field. Is there a way to add a JIRA number in that field and have it link automatically back to JIRA? Or how about setting a JIRA number as a linkable tag? We use this macro a lot to drag and drop documents onto a page and get version control (so long as we keep the filename the same), but we would also like to   somehow link or point these attachments back to the JIRA that created or updated that attachment (similar to how we can link Confluence docs in a JIRA issue).

  28. Its unbelievable that Atlassian not only hasn't fixed the file length issue ( CONF-22002 - Confluence renders attachments with long filenames with an ellipsis rather than a presenting the information to the browser and using css to limit the fieldwidth Resolved ), but that you guys don't even have it on a version roadmap (at least not on I saw that Steve Haffenden [Atlassian Bugmaster] removed Fix Version 5.1.4 on June 5th. I understand your new feature process, but this is not a new feature, its a bug. Not being able to display full filenames in any way without editing a VM file is un-acceptable. Please get this mapped and fixed!

  29. Anonymous

    This drives me nuts:  Why does the parameter column not match the actual parameters?

    For example, above it says that the parameter is "Filename Patterns," but in practice it is "patterns."

    Additionally, this page should also display the syntax or an example of the syntax for the macro.  For example:

    1. Sorry this is causing you frustration. The tables above list the parameters as they appear in the macro browser. If you are adding the macro parameters directly via storage format or wikimarkup you can refer to the specific docs for these, which do list the parameter names, for example Confluence Storage Format for Macros. There are links at the bottom of each macro page to the storage format examples, and where available, the wiki markup. 

      Hope this helps reduce the frustration.