Documentation for JIRA 4.2. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata

When file attachments are enabled, your users will be allowed to attach files and screenshots to JIRA issues. This requires space on the server for storing the attachments.
(warning) Attachments are not stored in JIRA's database and so will need to be backed up separately.

File attachments are enabled by default. If you wish, you can configure the way JIRA handles attachments, or disable this feature altogether.


  • your users must also have the Create Attachments permissions to attach files to issues
  • to allow users to attach a file when creating a new issue, you need to ensure that the 'Attachment' field is not hidden within the field configuration(s) associated with the specific issue type(s).

On this page:

Configuring Attachment Settings

  1. Log in as a user with the 'JIRA System Administrators' global permission.
  2. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard.
  3. Under the 'Global Settings' sub-menu in the left-hand navigation column, click the 'Attachments' link. This will display the Attachment Settings page, which states whether attachments are on or off:
  4. Click the 'Edit Configuration' link, which will display Edit Attachment Settings page:
  5. In the 'Attachment Path' field, choose the 'Use Default Directory' option. If you see more attachment path options than what is shown in the screenshot above, please refer to the note below.
  6. In the 'Attachment Size' field, specify the maximum attachment size. The default is 10485760 bytes (10 MB).
  7. (Optional) In the 'Enable Thumbnails' field, ensure that 'ON' is selected if you wish to display image file attachments as thumbnails (or miniature previews) when viewing an issue. When this setting is enabled, JIRA automatically creates thumbnails of the following types of image attachments:
    - GIF
    - JPEG
    - PNG
    Please refer to the info note below for more information about thumbnails. If you use Linux, please refer to the Linux note below.
  8. (Optional) In the 'Enable ZIP Support' field, ensure that 'ON' is selected if you wish to view the contents of zip files attached to an issue and allow all files attached to an issue to be downloaded as a single ZIP file.
  9. Click the 'Update' button to update JIRA's attachment settings.
    To attach files to issues, the appropriate users, groups or project roles must first be assigned the Create Attachments permission for the relevant project(s).
    To allow these users or group/project role members to delete their own attached files from issues, they must also be assigned the Delete Own Attachments permission for these projects too.
    There is no need to proceed any further if,
    - the permission schemes used by your project(s) already have the Create Attachments (and Delete Own Attachments) permission, or
    - your project(s) use JIRA's built-in Default Permission Scheme.
    However, if you wish to configure these permissions, proceed with the remaining steps below.
  10. Under the 'Schemes' sub-menu in the left-hand navigation column, click the 'Permission Schemes' link. This will display a list of all permission schemes in your JIRA system, and the projects which use each scheme.
  11. For each relevant permission scheme,
    1. Click the 'Permissions' link to edit the scheme's permissions.
    2. On the Edit Permissions page, locate Create Attachments within the Attachment Permissions section and click the 'Add' link.
    3. In the user selection options on the right of the Add New Permission page, select the relevant (groups of) users or roles and then click the 'Add' button.

      (tick) To allow these users or group/project role members to delete their own attachments, do not forget to assign them the Delete Own Attachments permission too.

Choosing a custom Attachment Path:


If you upgraded JIRA with an XML backup from a JIRA version prior to 4.2 and used a custom directory for your attachment path, you can choose between using this custom directory (which cannot be edited) or the default directory for your attachment path location. However, once you switch to using the default directory, you can no longer choose the custom directory option.

(The default directory location is the data/attachments subdirectory of the JIRA home directory.)

More information about thumbnails:

  • You can configure the Issue Navigator column layout to display the thumbnails in an Images column.
  • All thumbnail images are stored in JPEG format in the attachments directory, together with the original attachments. The thumbnail images are denoted by '_thumb_' in their file names.

Thumbnail image generation on Linux:

  • Your system must have X11 support. This web page details the minimum set of libraries needed to use JDK 1.4.2 under RedHat Linux 9.0.
  • The following java system property must be set: -Djava.awt.headless=true

Advanced Configurations

You can implement additional tweaks (described below) to modify the way JIRA handles attachments. These tweaks cannot be modified through JIRA's attachment settings (above). Instead, they are implemented by editing specific properties in the file.

Configuring Thumbnail Size

By default, thumbnails are 200 pixels wide and 200 pixels high. To change the dimensions of thumbnail images:

  1. Stop JIRA.
  2. In the file, edit the values of the following properties:
    • jira.thumbnail.maxwidth — thumbnail width in pixels
    • jira.thumbnail.maxheight — thumbnail height in pixels
  3. Delete all existing thumbnail images within the attachments directory (that is, those containing '_thumb_' in the filename).
  4. Restart JIRA.

After restarting JIRA, all thumbnails will be recreated automatically using the new dimensions.

Configuring Attachment Numbers on Issues

By default, JIRA shows a maximum of 30 attachments on an issue. To change this maximum value:

  1. Stop JIRA.
  2. In the file, edit the value of the property to the maximum number of attachments you want to show on an issue.
  3. Restart JIRA.

Configuring ZIP-Format File Accessibility

By default, JIRA allows you to access common ZIP-format files, with file extensions like '.zip' and '.jar' (Java archive files). However, there are numerous other ZIP-format files to which JIRA does not permit access by default. You can permit access to these files by doing the following:

  1. Stop JIRA.
  2. In the file, remove the extensions from the property of the file types whose contents you wish to access in JIRA.
  3. Restart JIRA.