# How to Use `--Force-Convert-All-HEICs` to Fix Incorrect JPEG Rotations in docker-icloudpd > Fix incorrect JPEG rotations in docker-icloudpd by using the --Force-Convert-All-HEICs flag. This ensures ImageMagick re-converts HEIC files for proper orientation. - Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd) - Tags: how-to-guide - Published: 2026-02-26 --- **TLDR:** Add the `--Force-Convert-All-HEICs` flag when running [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) to force ImageMagick to re-convert every HEIC file, overwriting existing JPEGs with correctly oriented versions after a mandatory 2‑minute safety delay. The `boredazfcuk/docker-icloudpd` container downloads iCloud Photo Library assets in their native HEIC format and can optionally convert them to JPEG for broader compatibility. A legacy bug in the original `heif-tools` conversion library caused generated JPEGs to inherit incorrect EXIF orientation tags, leaving images rotated sideways or upside‑down. The project has since migrated to **ImageMagick**, which handles orientation correctly, but existing JPEGs created by the buggy converter remain mis‑rotated. The `--Force-Convert-All-HEICs` flag solves this by triggering a full re‑conversion sweep. ## Why JPEG Rotations Fail in docker-icloudpd Early versions of the container relied on `heif-tools` to transcode HEIC files. That utility contained a bug that misapplied EXIF orientation data during conversion, causing the resulting JPEG to display with the wrong rotation in viewers that respect EXIF orientation (including most web browsers and photo apps). The maintainers replaced `heif-tools` with **ImageMagick** in the `icloudpd.dockerfile`, eliminating the bug for future conversions. However, this change does not retroactively fix JPEGs already on disk. To correct those files, you must force the conversion process to run again. ## What `--Force-Convert-All-HEICs` Does When passed to the entry‑point script [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh), this flag: 1. **Scans the entire download directory** for files ending in `.HEIC` (case‑insensitive). 2. **Re‑runs ImageMagick conversion** on every match, generating a JPEG with the same base filename. 3. **Overwrites existing JPEGs**, replacing the mis‑rotated legacy files with correctly oriented new ones. 4. **Enforces a 2‑minute safety delay** before starting, printing a warning that allows you to stop the container if the flag was invoked accidentally (since this operation destroys any manual edits made to the JPEGs). ## How to Use `--Force-Convert-All-HEICs` to Fix Rotated JPEGs Ensure the container is running, then execute the conversion command with `docker exec`. The script will pause for two minutes; if you do not wish to proceed, stop the container during this window. ```bash # Start the container if it isn't already running docker compose -f /path/to/docker-compose.yml up -d # Trigger the forced re-conversion docker exec -it icloudpd sync-icloud.sh --Force-Convert-All-HEICs ``` You will see output similar to: ``` WARNING: Force Convert All HEICs enabled. This will overwrite existing JPEG files. Waiting for 2 minutes before starting. Stop the container now to cancel. ``` After the delay, the script walks through the download folder defined in your configuration (specified in [`CONFIGURATION.md`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md)) and regenerates each JPEG. ### Re-converting External Mounts Only If you mount an external volume under `/mnt` and want to limit the operation to that directory, use the sibling flag: ```bash docker exec -it icloudpd sync-icloud.sh --Force-Convert-All-mnt-HEICs ``` This variant targets only the `/mnt` subdirectory, leaving files in the main download directory untouched. ## Technical Implementation Details The logic resides in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh), the container’s entry point. When the script parses command‑line arguments, it detects `--Force-Convert-All-HEICs` and sets an internal flag that bypasses the normal “skip if JPEG exists” check. The conversion itself invokes ImageMagick’s `magick convert` (or the wrapper function defined in the script), passing the HEIC source and JPEG destination. Because ImageMagick correctly interprets the orientation matrix in the HEIC’s metadata, the output JPEG contains the proper EXIF orientation tag (or is physically rotated, depending on the specific ImageMagick policy defined in the Dockerfile). As noted in [`CONFIGURATION.md`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md): > “This option is required as the `heif-tools` conversion utility had a bug that over‑rotates the JPEG files… The `ImageMagick` package… doesn’t have this problem.” ## Summary - **Root cause:** Legacy `heif-tools` library misapplied EXIF orientation during HEIC‑to‑JPEG conversion. - **Solution:** The `--Force-Convert-All-HEICs` flag forces ImageMagick to re‑convert every HEIC, overwriting old JPEGs with correctly oriented versions. - **Safety feature:** A mandatory 2‑minute delay prevents accidental data loss. - **Variants:** Use `--Force-Convert-All-mnt-HEICs` to target only external mounts. - **Key files:** [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) implements the logic; [`CONFIGURATION.md`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/CONFIGURATION.md) documents the behavior. ## Frequently Asked Questions ### Will `--Force-Convert-All-HEICs` delete my original HEIC files? No. The flag only affects JPEG outputs. Your original `.HEIC` files remain untouched in the download directory. The script overwrites existing JPEGs that share the same base filename, but it does not remove or alter the source HEICs. ### Can I stop the conversion after the 2‑minute delay starts? Yes. The 2‑minute countdown is a grace period designed specifically for cancellation. If you realize you invoked the flag by mistake, run `docker stop icloudpd` (or your container name) during this window. Once the delay expires and conversion begins, stopping the container will interrupt the process, but any files already processed will remain overwritten. ### What is the difference between `--Force-Convert-All-HEICs` and `--Force-Convert-All-mnt-HEICs`? `--Force-Convert-All-HEICs` scans the main download directory specified in your configuration and re‑converts every HEIC found there. `--Force-Convert-All-mnt-HEICs` restricts the operation to the `/mnt` subdirectory, which is typically used for external or secondary storage mounts. Use the latter when you only need to fix rotations on an external drive without touching the primary library. ### Does this fix affect future downloads? No. `--Force-Convert-All-HEICs` is a one‑time repair operation. Future HEIC files downloaded by the container will be converted using ImageMagick automatically (if conversion is enabled in your environment variables), and they will have the correct orientation from the start. You only need to use this flag again if you discover additional legacy JPEGs that were created before the ImageMagick migration.