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

> Convert HEIC to JPEG with docker-icloudpd. Set environment variables convert_heic_to_jpeg and jpeg_quality for custom ImageMagick conversion. Get high quality JPEGs.

- Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh) line 112).

## How the Conversion Works

When enabled, the conversion logic inside [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) invokes ImageMagick with the quality flag set to your configured value. The specific command structure is:

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

```

This command appears in multiple locations within [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/docker-compose.yml) file:

```yaml
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):

```dotenv
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) script provides CLI actions for batch processing existing files.

Convert all HEIC files in the download directory:

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

```

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

```bash
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:

```bash
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh).
- The conversion uses **ImageMagick** (`magick -quality`) executed within [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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.