Patch #43932
open
Add HEIC/HEIF image support (thumbnails, inline display)
Description
Summary¶
HEIC (High Efficiency Image Codec) has been the default photo format on iOS since 2017 (iOS 11) and is increasingly used on Android. When HEIC/HEIF files are uploaded as attachments in Redmine, they are treated as generic files — no thumbnails, no inline display via !filename.heic! syntax, and no lightbox preview. This is a code-level limitation, not an ImageMagick limitation.
The official Redmine Docker image (Debian Trixie base) already ships ImageMagick with full HEIC read support via libheif. MiniMime (used by Redmine) already resolves .heic → image/heic. The only barrier is hardcoded extension and MIME type whitelists in four files.
The attached patch adds HEIC/HEIF to these whitelists following the same pattern used when WebP support was added. Thumbnails are output as JPEG (not HEIC) because ImageMagick's HEIC support is read-only — it can decode but not encode HEIC. This mirrors the existing PDF → PNG thumbnail path.
Patch is against the 6.1-stable branch (Redmine 6.1.2).
Changes¶
Four files modified, all following existing patterns:
app/models/attachment.rb— Addheicandheifto theimage?method's extension regex. Controls whether an attachment is treated as an image throughout Redmine (thumbnails, lightbox, inline display).app/helpers/application_helper.rb— Addheicandheifto the inline image rendering regex. Enables!photo.heic!syntax in issue descriptions and wiki pages. Note: HEIC renders inline in Safari (which has native HEIC decoding) but not Chrome/Firefox. This does not degrade — non-supporting browsers simply don't render the inline image, identical to current behavior for any unrecognized format.lib/redmine/thumbnail.rb— Two changes: addimage/heicandimage/heifto theALLOWED_TYPESconstant (MIME type whitelist checked before invoking ImageMagick), and add anelsifbranch in thegeneratemethod that forces JPEG output for HEIC/HEIF input using ImageMagick'sjpg:output format prefix. Without this, ImageMagick fails with "no encode delegate for this image format 'HEIC'" because its HEIC support is read-only. Follows the same pattern as the existing PDF → PNG branch.app/controllers/attachments_controller.rb— Add anelsifbranch indetect_content_typethat returnsimage/jpegfor HEIC/HEIF thumbnails. The thumbnail file contains JPEG data but the method would otherwise return the original attachment'simage/heiccontent type. Follows the existing PDF → PNG precedent.
Testing¶
Tested on Redmine 6.1.2 with ImageMagick 7.1.1-43 (libheif 1.19.8, libde265 1.0.15) and 500+ existing HEIC attachments:
- Thumbnails display correctly in issue attachment lists
- Lightbox preview works
- Inline
!photo.heic!syntax renders in Safari - No impact on existing image formats (JPEG, PNG, GIF, WebP, BMP)
- No database migration required — MiniMime already resolves the MIME type correctly
Prerequisites¶
ImageMagick must be compiled with libheif support. The official Redmine Docker images based on Debian Trixie (Redmine 5.1.12+, 6.x) include this out of the box. Verify with: convert -list format | grep -i heic — expected output includes HEIC HEIC r-- (read-only is sufficient).
Precedent¶
The WebP format was added to these same whitelists via the same mechanism. HEIC/HEIF follows the identical pattern.
Files
Updated by Go MAEDA 18 days ago
Thank you for submitting the patch.
This patch enables both inline and thumbnail display of HEIC/HEIF images. However, I suggest limiting support to thumbnail display in Redmine.
Currently, only Safari supports displaying HEIC/HEIF images, while other browsers such as Chrome, Edge, and Firefox do not. If inline display is enabled, the appearance of issues and wiki pages would differ depending on the user's browser.
In contrast, thumbnails are generated by converting images to JPEG format via ImageMagick, so they can be displayed consistently across all browsers.
I will update the patch accordingly to support thumbnail display only.
Updated by Go MAEDA 16 days ago
I realized that adding a feature to Redmine that converts HEIC images into JPEG thumbnails may involve patent risks.
HEIC uses the HEVC (H.265) compression format, which is covered by multiple patents. Converting a HEIC image to JPEG requires decoding HEVC data. This decoding process may be covered by those patents.
Access Advance states on its FAQ page that "You most likely need a license if you sell any products that have HEVC/H.265 encoding and/or decoding capability/functionality" . Redmine itself is open source and not sold, so this may not apply directly. However, if Redmine is used in a SaaS service or a commercial product, a patent license may be required.
If this feature is included in Redmine, some users—especially those running SaaS or commercial services—may face patent risks.
Because this feature could expose some users to patent risks, I think it would be better not to include it in the core of Redmine.
Updated by Peter Petrik 16 days ago
Thank you for looking into this, I appreciate the thoroughness.
My perspective on the HEIC patent risk:
Redmine does not implement HEVC decoding¶
This patch adds format names to string whitelists — extension regexes and MIME type arrays. It does not implement, ship, or bundle any HEVC decoder. The actual HEVC decoding is performed by libheif and libde265, which are system-level libraries maintained by their own projects, shipped by Debian, and already bundled into ImageMagick.
The Access Advance FAQ states: "You most likely need a license if you sell any products that have HEVC/H.265 encoding and/or decoding capability/functionality." Redmine has no HEVC decoding capability. ImageMagick does, via libheif. That distinction matters — the patent obligation falls on the software that implements the decoder, not on every application that calls ImageMagick.
The capability already exists in Redmine's environment¶
The official Redmine Docker images (Debian Trixie base) already ship ImageMagick compiled with libheif. Any Redmine user running these images already has HEVC decoding capability on their system, regardless of whether Redmine's whitelists include heic. This patch does not add or enable that capability — it only allows Redmine to recognize a format that ImageMagick can already process.
Precedent within Redmine¶
Redmine already generates PDF thumbnails via Ghostscript, which has its own licensing considerations (AGPL). The project did not decline PDF thumbnail support on that basis. The relationship between Redmine and ImageMagick's HEIC support is analogous — Redmine delegates to an external tool and is not responsible for that tool's licensing or patent posture.
Broader open-source precedent¶
Major open-source projects — GIMP, FFmpeg, VLC, Nextcloud, Photoprism — all support HEIC via the same libheif/libde265 stack without treating it as a patent risk for their projects. Debian ships libheif and libde265 in its main repository (not non-free), reflecting their assessment that these libraries are distributable.
Summary¶
The patent risk, to the extent it exists, sits with the HEVC decoder implementation (libde265/libheif) and the operating system that distributes it (Debian). Redmine adding heic to a whitelist does not shift that risk to Redmine or its users any more than the existing PDF thumbnail support shifts Ghostscript's licensing to Redmine.
I believe the patch can be included without patent concern, but I understand if the project takes a more cautious position. Either way, thank you for considering it.