Attachments Macro

The Attachments macro displays a list of files attached to a page.  

 It also allows users (with appropriate permissions) to:

  • upload a file to the page, directly from the list 
  • edit attachment properties and labels
  • delete an attached file (this deletes all versions of the file)
  • preview image attachments
  • edit attached Office and PDF documents using the Office Connector.
  • download all files attached to the page. 

Note: you can use the macro parameters to turn off previews if you have very large attachments. 

Screenshot: The Attachments macro, showing details of an attachment

Using the Attachments Macro

To add the 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 Autocomplete for links, files, macros and mentions.

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




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 Add, Remove and Search for 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 updated date in reverse chronological order (newest first)
  • size – sorts largest to smallest
  • name – sorts alphabetically
  • created date - sorts by creation date in reverse chronological order (newest first)
Sort Order
ascending Used 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.
Show Previews
true Used to display a preview of the attached file. If true, preview will be visible when the list item is expanded.

Code examples

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

Macro name: attachments

Macro body: None.

Storage format example

Wiki markup example

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

45 Archived comments

  1. User avatar

    Matin Schiemann

    Having to use a regex for filtering files in the attachments of a page is the absolute opposite of wiki/easy. Please substitute it with standard operating system wildcard possibilities (soon). Or at least give the documentation of the makro some more helpful examples which spares users to install tools and learn everything listed on

     CONF-25109 - Make the regex a standard filename pattern improvement request raised.

    03 Apr 2012
  2. User avatar

    David Rosalia

    The examples given for using the regular expressions are not very user friendly.  I'm used to using regular expressions and even I had a hard time understanding the documentation.

    Some simple examples would be nice.  For example :


    17 Oct 2012
  3. User avatar

    James Grout

    Is it possible to adjust the column width of the attachment list? For example I would like to expand the Name column so that I may see the full file name of my attachments.

    17 Oct 2012
    1. User avatar

      Emile van den Ende

      Hi James,

      You could put the attachments macro inside a column or section. Those can be adjusted in size.




      Edit; don't think you are able to change the width of the columns though.

      07 Jan 2013
  4. User avatar

    David Rosalia

    I have tried to use the | operator with this plugin in Confluence without success.  Is there a substitute operator for this?

    27 Nov 2012
  5. User avatar

    ChangJoon Lee

    Please, let me use more than one in a page.

    Please let me specify ID, currently it breaks if I use two instances on the same page.

    Confluence 5.1



    29 Mar 2013
  6. User avatar


    Hi, Does anyone encountered problems displaying old versions of the attachment when access thru the page but the function works inside the Attachement page?

    11 Apr 2013
  7. User avatar


    Are you able to add more column headings?  Right now I get Name of file (almost always truncated due to restricted width, which is another issue) and "modified".


    Adding additional column headings like Comments or labels would be veryhandy.


    Also, the drag and drop box is nice when you first see it but after a while, when you know you can just drag and drop, just takes up real estate on the screen and pushes content down off of the page...

    26 Apr 2013
  8. User avatar

    Chris Wallingford

    I find that the Attachments macro often truncates my file names. I can see the whole name in the tooltip, but not in the page content. There's plenty of space to display the whole name. Is there a workaround or enhancement request to address this?

    05 Jun 2013
    1. User avatar

      Adrian Smith

      I would also like to be able to increase the column width to show the full file name

      09 Aug 2013
    1. User avatar

      Silvio Moser

      Me too.

      07 Mar 2014
      1. User avatar

        Adrian Reid [Atlassian]

        Hi Adrian and Silvio, I just tried to replicate the problem on Confluence 5.4 but the Attachments macro displays the file names correctly and the columns provide plenty of width. A screen shot would be the best way to identify the problem. If you could create an issue with Support you could attach a screenshot and we can get a better idea of the problem.

        09 Mar 2014
  9. User avatar


    Hi, does anyone know of a way to see download statistics for an attachment? I just mean something as simple as "How many times has this file been downloaded?"


    10 Jun 2013
    1. User avatar

      Debbie Augusteyn


      I recently logged a support ticket for this exact question. The answer is:

      Confluence doesn't such feature as bundled. However I could find a third party plugin that it seems that does it, but that will not work for the version that you're in, only Confluence 5 series.

      • [Google Analytics      Confluence Integration

      A feature request has been submitted so please vote for it:

      03 Oct 2013
  10. User avatar


    Ideally I'd like to have 4 columns: File Name, Last Modified, Size, and # of downloads.

    10 Jun 2013
  11. User avatar


    can the preview of the file be shown to the left, or can there be a link to expand all items?  We're trying to figure out how to use this for an asset library (for example - browse thumbnails of images)

    12 Jun 2013
  12. User avatar


    can this be altered so that only the name and comment labels are visible?

    12 Jun 2013
  13. User avatar

    Kathryn Moye

    Does anyone else have issues with using the Attachments macro in a Scaffold?  When I try to attach files and I haven't saved the page, my scaffold data field's contents are deleted.  The Browse and Attach buttons should be grayed out in edit mode if they don't work there.


    17 Jul 2013
  14. User avatar



    I am experiencing a "Page Not Found" error attempting the following scenario:

    • I have a parent page within a space
    • I have five child pages to that parent page
    • I want to display the files attached to each child page from sections within the parent page
    • I add the "Attachments Macro" five times to the parent page to reference files attached to the five child pages
    • In each of the Attachments Macro parameters settings I correctly add the "Page Title" for each respective child page
      • (Confluence even auto-completes the names, indicating to me they are recognized as existing)
    • BUT... The parent page displays "Page not found: <correct title of page>" for all five of the spots where the macro exists


    Here's what I've checked and tested:

    • I read in the documentation the "Page Title" parameter will list files attached from other pages if the other page name is entered.  I have checked and added the correct page names containing the attachments I would like to appear in the macro.
    • I thought it was some issue with a parent page trying to list attachments from one of it's own child pages... so I tried using the macro in one of the child pages to show attachments on the parent page (entering the parent page name in the "Page Title" parameter)... but the same error appears.
    • The macro works correctly within each child page leaving the "Page Title" blank (which will reference the current page if left blank).
    • I just can't get the macro to recognize the pages, and therefore attachments, I am trying to view


    So... what is going wrong with this scenario?



    04 Sep 2013
  15. User avatar


    Is it possible to have this macro also pull in all files from child pages?

    09 Sep 2013
    1. User avatar

      stacey richter

      Could someone please help me to figure out which macro to use in order to specify a set of pages to pull attachments from? I think I've tried every attachment and search macro & tried any number of ways to select the range of pages. I'm not the best regular expression user, so maybe I'm doing something wrong, or maybe confluence simply doesn't let you do this? Pls help.

      05 Dec 2013
    1. User avatar

      Mikael Mikkola

      That would be great. If not, is it possible to pull in all files in the wikispace?

      10 Mar 2015
      1. User avatar

        Rachel Robins [Atlassian Tech Writer]

        Sounds like theSpace Attachments Macrowill do the trick. This macro shows all the attachments from any page in a space. 

        10 Mar 2015
  16. User avatar


    I also need the full file names to display.  I tried putting the macro in a column/section and I could resize the screen but the file names are still truncated as they are in the larger screen.

    18 Sep 2013
  17. User avatar


    Hello all,

    I'm looking how to use this macro by "excluding" some files (obsolete)

    Is it possible to have this possibility?

    Would be great also to have a hand on the column width parameter to adjust the macro for big name files. Or to allow the macro to show the full name with 2 or 3 lines if required...

    Thank all for help


    02 Jan 2014
    1. User avatar

      red sonja

      i would need this feature too - best a mix of defining fileformats with certain expressions within the filnenames (eg show only pptx, but none having 'interview' as part of the filname).

      at least one of theese two options would be very helpful!

      08 Oct 2014
  18. User avatar

    denis cottin

    Hello all,

    I'm looking how to use this macro by "excluding" some files (obsolete)

    Is it possible to have this possibility?

    Would be great also to have a hand on the column width parameter to adjust the macro for big name files. Or to allow the macro to show the full name with 2 or 3 lines if required...

    Thank all for help


    This message is a copy of anonymous to be aware if somebody answer...

    02 Jan 2014
  19. User avatar

    James Roberts

    How does one go about using the preview parameter for this macro? It is documented above but it does not show up in the Macro Editor and if you type it in manually it is not honored.

    Any help is greatly appreciated.

    15 May 2014
    1. User avatar

      Rachel Robins [Atlassian Tech Writer]

      Hi James, What version of Confluence are you using? This parameter was added in Confluence 5.5.  It is a checkbox in the macro browser.  

      16 May 2014
      1. User avatar

        James Roberts


        Thanks for the clarification. I should have done a better job of realizing that it was included in 5.5. We are running 5.2.5 and I did not see it there. Thank you for the information.

        16 May 2014
  20. User avatar

    Gary McCormick

    I know by default it isn't possible, but does anyone have a workaround to use OR for the attachment labels instead of and?

    18 Jul 2014
  21. User avatar

    jim fisher

    I am using multiple attachment macros on one page that are displaying different results based on both regex and labels.  Due to the limitations of the regex interpreted I can't exclude certain attachments that match the expression in the first macro.  As a workaround I am using labels to distinguish between them.  The drawback to this is that labels have to be managed and updated manually.  I was wondering if there is a way to automatically apply labes to an attachment based on which macro the file is dropped into.  Thanks.

    13 Aug 2014
  22. User avatar

    Eric Sebian

    Is it possible to have 2 different attachment macros on the same page. for instance, a list of QA test procedures for instance A and a separate attachment macro for QA test procedures for instance B. Please advise. 



    11 Dec 2014
    1. User avatar

      Giles Brunning [Atlassian Technical Writer]

      Hi Eric,

      You can certainly have more than one attachments macro on a page, and you can filter what's shown in them using labels or file names. So you could add a label to any attachments for scenario A, and another label to any attachments for scenario B, which would then enable to attachment macros with different results.

      Not quite sure what you mean by instance A & B though, so I hope that answers your question.

      11 Dec 2014
      1. User avatar

        petr novotny


        I've tried to create more than one attachments macro on a page and it works well. A used labels to separate files for each one macro. Documents appears in correct sections (macros). Thats OK.

        My problem is with downloading "all documents" from one macro section. The result is that the archive with all documents of whole page is generated and downloaded. is it possible to get download all files just from one selected macro? 

        Thnx  for answer


        28 Jan 2015
        1. User avatar

          Rachel Robins [Atlassian Tech Writer]

          Hi Petr, the Download All does download all attachments on the page, regardless of what you've chosen to display in the macro.  

          I'm not aware of a way to download just a subset of attachments sorry. 

          28 Jan 2015
          1. User avatar

            Shawn Erquhart

            The sole purpose of this macro is to display a subset of page attachments - the fact that it does so, and then downloads every attachment on the page instead of the subset it's displaying is an antipattern. Is there any chance of Atlassian fixing this feature to produce expected results?

            07 Feb 2015
  23. User avatar

    Eric Sebian

    Hi Giles.

    Thanks for getting back to me so quickly. I think I am doing something wrong because when I add 2 attachment macros Confluence just creates a copy of whatever I try to add to 1 specific attachment macro. I have an image but there is no way to attach it.  Please advise. 

    12 Dec 2014
    1. User avatar

      Giles Brunning [Atlassian Technical Writer]

      Hi Eric,

      I think you'd be best to contact support about this one. They can run through the scenario with you and troubleshoot any issues.

      14 Dec 2014
  24. User avatar

    Hugh Bathurst

    The Attachments Macro is most useful, thanks Rachel for alerting us, does anyone know anyway we can display filesize via this macro (we're trying to give users a sense of load times as we advance towards 3Mb's loading in 3 seconds at multiple locations). Cheers - Hugh

    18 Feb 2015
  25. User avatar

    Siddheshwar mhetre

    Hello All,

     Can we delete multiple attachments? using any User macros or plugin?

    14 Apr 2015
    1. User avatar

      Hugh Bathurst

      I believe this can only (??) be done currently by deleting the page with the multiple attachments. My initial tests suggest this approach is usable.

      15 Apr 2015
    1. User avatar

      Hans-Peter Geier

      Hi, you can do this easily using the WebDav interface. (You can find it documented here)

      15 Apr 2015
  26. User avatar



    I have a page using the attachment macro, but it's gotten to the point where we have an extremely long list of files attached. Is it possible to collapse the older files? For example, is there a way to embed an Expand macro in the Attachments macro? Any other options?


    08 Jul 2015
    1. User avatar

      Giles Brunning [Atlassian Technical Writer]


      Unfortunately, I don't think so. Feel free to make an improvement suggestion so we can gauge the interest.

      20 Jul 2015
Powered by Confluence and Scroll Viewport