How to Convert HEIC Files to JPEG in docker-icloudpd: Quality Settings Guide

Set convert_heic_to_jpeg=true and specify jpeg_quality (0-100) in your environment variables to automatically convert iCloud HEIC downloads to JPEG format using ImageMagick.

The docker-icloudpd container automates downloading photos from iCloud, and it includes built-in support for converting Apple's HEIC format to the more widely compatible JPEG format. By adjusting two configuration parameters defined in init_config.sh, you can control whether conversion happens automatically and set the exact compression quality for the output files.

Configuration Options

docker-icloudpd exposes two environment variables that govern HEIC conversion behavior. These are processed during container initialization and stored in the generated configuration file.

convert_heic_to_jpeg Enables automatic conversion after each download. When set to true, the container converts every .HEIC file to JPEG immediately after the download completes, while preserving the original HEIC file. The default value is false (see init_config.sh line 85).

jpeg_quality Controls the ImageMagick compression level for generated JPEGs. Accepts integer values from 0 (lowest quality, smallest file) to 100 (highest quality, largest file). The default is 90 (see init_config.sh line 112).

How the Conversion Works

When enabled, the conversion logic inside sync-icloud.sh invokes ImageMagick with the quality flag set to your configured value. The specific command structure is:

magick -quality "${jpeg_quality}" "${heic_file}" "${jpeg_file}"

This command appears in multiple locations within sync-icloud.sh, including the single-file conversion routine at line 1509 and the batch conversion function at line 1683. After conversion, the script preserves the original file's timestamp by running touch --reference="${heic_file}" "${jpeg_file}" to ensure the JPEG maintains the same modification time as the source HEIC.

Setting Up HEIC to JPEG Conversion

To enable automatic conversion, add the environment variables to your container configuration.

Docker Compose Configuration

Add the variables to your docker-compose.yml file:

services:
  icloudpd:
    image: boredazfcuk/docker-icloudpd
    environment:
      - convert_heic_to_jpeg=true
      - jpeg_quality=85

Environment File Configuration

Alternatively, configure these in your .env file (as shown in docker-compose/example.env lines 25-28):

convert_heic_to_jpeg=true
jpeg_quality=85

Restart the container after modifying these values to apply the changes.

Manual Conversion Commands

You can trigger conversion on demand without waiting for the next download cycle. The sync-icloud.sh script provides CLI actions for batch processing existing files.

Convert all HEIC files in the download directory:

docker exec -it icloudpd ./sync-icloud.sh --convert-all-heics

Force conversion even if JPEGs already exist (overwrites existing files):

docker exec -it icloudpd ./sync-icloud.sh --force-convert-all-heics

Temporary Quality Override

To run a one-time conversion with different quality settings without changing the permanent configuration, override the variable at execution time:

docker exec -e jpeg_quality=70 icloudpd ./sync-icloud.sh --convert-all-heics

Summary

• Set convert_heic_to_jpeg=true to enable automatic JPEG generation for all downloaded HEIC files.
• Control output fidelity with jpeg_quality (default: 90, range: 0-100) as defined in init_config.sh.
• The conversion uses ImageMagick (magick -quality) executed within sync-icloud.sh (lines 1509, 1683, 1752, 1784).
• Original HEIC files are retained; JPEGs inherit the source timestamps.
• Use --convert-all-heics or --force-convert-all-heics flags for manual batch processing of existing libraries.

Frequently Asked Questions

What is the default JPEG quality if I don't specify it?

According to the docker-icloudpd source code in init_config.sh at line 112, the default jpeg_quality value is 90, which provides a good balance between image fidelity and file size.

Does enabling HEIC conversion delete the original files?

No. When convert_heic_to_jpeg is enabled, the container creates a JPEG copy alongside the original HEIC file. The originals remain in the download directory unless you manually delete them or use the separate --remove-all-jpgs option (which removes JPEGs, not HEICs).

Can I convert existing HEIC files that were downloaded before I enabled the option?

Yes. Run the manual conversion command docker exec -it icloudpd ./sync-icloud.sh --convert-all-heics to batch-process all existing HEIC files in your download directory. Add the --force-convert-all-heics flag to overwrite any existing JPEGs with new conversions using your current quality settings.

What happens if ImageMagick is not installed in the container?

The docker-icloudpd image includes ImageMagick (magick) by default. If the binary is missing, the conversion functions in sync-icloud.sh will fail to execute the magick -quality command and will skip processing those files. Ensure you are using the official boredazfcuk/docker-icloudpd image which bundles this dependency.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}