Creating a Smart Apple Photos to Immich Migration Workflow

Overview of the Solution

Moving from Apple Photos to Immich can be challenging - especially when you want to preserve your carefully organized albums. In this guide, I'll explain how to set up an efficient pipeline that exports your photos from Apple Photos to Immich while maintaining album structure and controlling server load.

My use case for Immich is explicitely not a backup or a photos organizer. I want to keep doing all that in Apples Photos App. Immich has the sole purpose of privately sharing the pictures with family and friends. For me it's basically the iCloud replacement with "unlimited" storage.

The way I have it setup is:

OSXPhotos extracts the photos to a folder on my local Mac and then rsyncs that whole folder to a designated directory on the Raspberry Pi. This directory is NOT the Immich External Library directory

On the Raspberry Pi I have an external library directory setup on an external drive. In my case it's named "raw_images". The Immich_Scripts/add_albums_slowly_to_raw_images.sh script moves / copies the album directories from the designated directory to the "raw_images". This way the Raspberry Pi doesn't overload with hundreds or thousands of pictures to process. I've seen it happen which is why I'm manually slowing down this processing. I've already limited the resources for the Immich containers, and I've reduced the job concurrency to 1 job for each job category... the Pi would still freeze up after a while.

I have the raw_images folder so that if I have to re-install Immich or if something is going wrong with it, I can just spin up a blank version of it, point it to that raw_images folder and it will re-build itself. Well, I would have to slowly feed it the pictures, but they are in one place already.

I strongly recommend setting up ssh keys to access your server, but I'm sure that everyone reading this already knows.

This workflow consists of three main components:

1. Mac-side export: Extract photos from Apple Photos libraries while preserving album structure
2. Controlled import: Transfer files to Immich server in small batches to prevent overwhelming the system
3. Automatic album creation: Convert folder structures into Immich albums

Part 1: Setting Up osxphotos on macOS and preparing the Immich server

First, we need to set up the osxphotos tool which can extract photos from Apple Photos libraries.

1. Create a Python virtual environment:

   python3 -m venv ~/.python_venv/osxphotos-env # I would create the virtual environment in this repository
   source ~/.python_venv/osxphotos-env/bin/activate
   python3 -m pip install osxphotos

2. Install helper scripts:

   • osxphotos_export_libraries.sh: Main wrapper script for exporting
   • osxphotos_before_export.py: Handles folder name formatting before export
   • osxphotos_after_export.py: Cleans up folder names after export

3. Export workflow: The main script automates the process:

   ./osxphotos_export_libraries.sh /path/to/Photos.photoslibrary

   This script:

   • Exports photos organized by album structure
   • Preserves metadata including album names
   • Handles special characters in album names
   • Filters out unwanted file types (like .orf raw files)
   • Syncs the exported photos to your Immich server

4. Setup Immich: On Immich you will have to setup an external library. Read the Immich Docs on how to do that. In my case that is the raw_images folder

   Get Library ID: curl -L 'https://yourimmich.example.com/api/libraries/' -H 'Accept: application/json' -H 'x-api-key:ADMIN-API-KEY'

   Add this library UUID to IMMICH_LIBRARY_ID in /Immich_Scripts/add_albums_slowly_to_raw_images.sh

Part 2: Controlled Importing to Immich

The add_albums_slowly_to_raw_images.sh script is the key to preventing server overload:

1. Batch processing:

   • Processes photos in small batches (default 15 files)
   • Monitors server CPU load before continuing
   • Waits for CPU to stay below threshold before processing more files

2. Smart API integration:

   • Triggers Immich library scan API calls after each batch
   • Allows server to process one batch completely before starting the next

3. Duplicate prevention:

   • Uses -n flag with cp/mv to avoid processing existing files
   • Filters out unwanted formats (like .orf files)

Part 3: Automatic Album Creation

The final stage converts your folder structure to Immich albums:

1. Docker-based automation: Uses the immich-folder-album-creator tool to convert folders to albums

   docker run \
     -e SYNC_MODE="1" \
     -e UNATTENDED="1" \
     -e API_URL="http://server-ip:2283/api/" \
     -e API_KEY="your-api-key" \
     -e ROOT_PATH="/usr/src/app/external" \
     salvoxia/immich-folder-album-creator:latest \
     /script/immich_auto_album.sh

2. Integration:

   • Automatically runs after all photos are imported
   • Waits for server load to decrease before starting

End-to-End Process

1. On your Mac: Export from Apple Photos

   ./osxphotos_export_libraries.sh /path/to/Photos.photoslibrary

2. On your Immich server: Process the photos in batches

   ./add_albums_slowly_to_raw_images.sh /path/to/source_directory

3. The server script automatically:

   • Processes files in small batches
   • Triggers library scans after each batch
   • Creates albums from folders when complete

Benefits of This Approach

1. Preserves organization: Your album structure is maintained
2. Server-friendly: Prevents overwhelming your Immich server
3. Automated: Minimal manual intervention needed
4. Resilient: Can be stopped/restarted without issues
5. Filters: Automatically excludes unwanted file types

By following this workflow, you can migrate large Apple Photos libraries to Immich while maintaining your album organization and ensuring your server remains responsive throughout the process.