How to Use `--Force-Convert-All-HEICs` to Fix Incorrect JPEG Rotations in docker-icloudpd

TLDR: Add the --Force-Convert-All-HEICs flag when running 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, 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.

# 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) 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:

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, 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:

“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 implements the logic; 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.

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