Skip to content

Switch from Immich

Install with Manager and bring your Immich library Watch on YouTube

Switching from Immich is a guided, one-time import. On Noodle Gallery? See Switch from Noodle Gallery. Frameleaf Manager brings your accounts, albums and library records into a new Frameleaf database, and your photos and videos stay right where they are.

Immich compatibility ended on October 15, 2026

Section titled “Immich compatibility ended on October 15, 2026”

Support for Immich backward compatibility ended on October 15, 2026. Since that date, Frameleaf develops its own database and processing system independently. Frameleaf is its own application rather than a drop-in replacement for an Immich container, and Immich can’t open its database.

You can bring an Immich 2.0 or later library into Frameleaf with the one-time Manager import below. After the import, your library lives in Frameleaf; the two applications don’t share or swap a database.

Change What it means for you
PostgreSQL 19 Frameleaf uses its own PostgreSQL 19 database with integrated vector search. Manager creates a fresh database and imports your library records; your original Immich database stays separate.
No Redis for jobs or queues Background job state lives in PostgreSQL alongside your library records. You no longer need a separate Redis or Valkey service for queues.
An integrated database built for speed and reliability Indexed search and durable job progress keep browsing responsive and background processing dependable. Progress survives restarts, interrupted work recovers, and you can review failed jobs.
A library you can use straight away After the import, Frameleaf opens at once. It checks every original, makes thumbnails and builds search and faces in the background, and shows how far it has got.
More visibility into your library Library care, Activity and Computers & background work show what has been checked, what is still processing and what needs your attention.

With fewer services to run, there’s less to maintain. Processing speed depends on your server, storage and library size. See Database storage and recovery and Jobs and queues for details.

Your Immich version What happens
2.0 or later You can import. This includes every 2.x and 3.x release.
Newer releases (such as 3.3 and later) Usually fine. Manager imports them as long as the parts of the library it reads haven’t changed. If they have, Manager tells you before anything changes.
1.x Not supported. Upgrade Immich to 2.0 or later first, then import.

You don’t need to be on the very latest Immich. Manager brings an older 2.x or 3.x library up to date as it reads it, making the same clean-ups a normal Immich upgrade would. It only reads your Immich library and never changes it.

  • Check your Immich version. You need Immich 2.0 or later. If you’re still on Immich 1.x, upgrade Immich to 2.0 or later first, then come back. Manager checks your installation before anything changes, so you’ll know straight away if something isn’t ready.
  • Make your own backup. Keep a usable Immich database backup and a separate backup of all media, including external libraries (Frameleaf calls these connected folders). Manager’s database recovery checkpoint covers the database, not your photos or videos.
  • Plan some downtime. Immich stays stopped while Manager imports and prepares the library. Pause phone uploads and any other clients that write to it.
  • Prepare storage. Leave room on a local disk for the new database and recovery files. Your existing database directory stays as it is.
  1. Follow Install with Frameleaf Manager to start Manager on the host running Immich and create your Manager administrator. Stop at Choose how to begin, before setting up a new library.
  2. Under Found on this server, select Review import on the Bring your photo library card. If Manager hasn’t found Immich yet, select Find installations. Pick your Immich installation and select Review library & settings. Leave the source running for discovery; Manager stops it during the import.
  3. On Library & settings, check Preserved media mappings and Settings compatibility. If Manager says some settings need review, open Advanced settings and remove or rename them.
  4. Under Storage & access, give the library a Library name, choose where the new Database and Backups go, and choose the Frameleaf port and a Frameleaf release. You can keep Immich’s port, normally 2283: Manager stops Immich before Frameleaf starts. Under Processing, turn on Enable beside Machine learning if you want face recognition and smart search.
  5. Disable any other scheduler or service that could restart the Immich containers, then tick the box that says Docker or Unraid manages startup. Tick I’ve reviewed the mappings and settings that need attention. too.
  6. Select Review database backup. On Database backup, Manager explains that only the database is backed up and your photos stay in place. When Manager already has a verified database backup from the last 24 hours, it reuses it and this step is skipped.
  7. Select Check this server. Manager checks Docker, folders, free space and the port, and shows every problem at once. See Problems Check this server can report. When it’s clear, select Review the switch.
  8. On Ready to switch to Frameleaf, look over the cutover plan. Tick I understand the original app will stay stopped and this backup covers only the database. and select Start import. You can close the page and come back to the recorded progress.

The steps along the top are Installation, Library & settings, Database backup, Checks and Import.

Manager library and settings review showing preserved media paths and access modes, settings needing attention and the import summary.

Review each media location and its read-only or read-write access. Check any settings Manager says need attention, such as an external sign-in callback that points to the Immich address, before moving on. Select the image to view it at full size.

Manager stops the source writers, saves a current database recovery copy, and imports into the fresh Frameleaf database. It can reuse a verified recovery backup from the last 24 hours, and always reads the current, stopped source for the import. It then checks the imported records, permissions and original files before starting Frameleaf.

Your media stays in place. Manager doesn’t copy or move your library. It reads those locations during the import and hands them to Frameleaf once everything checks out. From then on, keep Immich stopped so Frameleaf is the only app using that media.

Your accounts and their local password information, photo and video records, ownership and access controls all come across, whichever 2.x or 3.x release you’re on. So do:

  • albums, album owners, shared members and the photos in each album
  • tags, memories, people and faces
  • share links, partner sharing and other sharing relationships
  • descriptions, ratings, favourites, edits and Live Photos
  • sidecar files and converted video copies that older Immich releases kept alongside your photos and videos

Locked, hidden and deleted items keep their state.

Older Immich releases left a few things behind that a normal upgrade would fix. Manager fixes them as it imports, so you end up with what an up-to-date Immich would have:

  • Hidden Live Photo stills come back. Some older releases accidentally hid the still image of a Live Photo. It’s visible again in Frameleaf.
  • Other people’s photos stay private. Because of an old Immich bug, a face or memory could point at a photo owned by someone else. Those entries are left out, so nobody sees a photo that isn’t shared with them.
  • Albums with no owner are left out. Immich 3.0 and 3.1 could leave an album with no owner. Immich 3.2 removes these, and so does Manager.
  • “0 stars” becomes “no rating”. Before Immich 2.6, some photos were saved with a zero-star rating. In Frameleaf they simply have no rating.
  • Countries aren’t listed twice. Immich 3.3 spells some country names differently. Manager matches them to Frameleaf’s names so each country appears once in Places.

You’ll sign in again and reconnect your apps, because sessions and API keys start fresh. Use the Frameleaf apps and create new API keys for your integrations. Manager carries over supported settings for you to review during setup.

These don’t come across:

  • people shared between accounts, a feature added in Immich 3.3
  • text found in photos, if you’re importing from a release older than Immich 2.2
  • plugin credentials, workflow definitions, old job queues and notification history

Frameleaf then builds fresh metadata, thumbnails, search and face data with its own processing system. That work carries on in the background after you finish setup.

  1. When Manager shows Your import is in Frameleaf, continue through Make it yours. Library preparation carries on in the background. When Frameleaf asks you to Sign in to finish setting up, enter your Immich administrator’s email and password as Admin email and Password and select Sign in and continue.
  2. Follow the Setting up your library bar while Frameleaf checks your files and builds thumbnails, search and faces. See While Frameleaf sets up your library.
  3. Check your accounts, albums and item counts. Open a few photos, play some videos, and check private and shared content with the right accounts.
  4. Install and connect Frameleaf’s native iOS app or Android app, then confirm the new server address before resuming uploads.
  5. Export your recovery configuration from Manager and set up database and media backups.

You don’t wait for the whole library to be processed. Frameleaf opens as soon as your accounts, albums and photos are imported, and a bar called Setting up your library shows the rest, with about how long is left:

Step What happens
Library imported Done when you arrive. Browse, search by name and share while the rest finishes.
Checking original files Each original is read once and compared with the checksum recorded when it was added. A file that doesn’t match is kept and listed in Library care.
Making thumbnails Runs at the same time as the file check.
Smart search, faces and videos Searching by what’s in a photo, grouping faces into people and getting videos ready to play. Starts by itself when the file check is finished.
  • You can keep using Frameleaf. Setup carries on if you close the page or the server restarts.
  • Pause stops it for a while and Resume carries on from where it stopped. Nothing is lost while it’s paused.
  • If the file check didn’t finish, the bar says so and names how many files need a look. Select Check again to finish them, or open them in Library care.
  • Stop setup ends it early. Stop setup and let the server run? explains that Frameleaf starts the work setup was holding and stops showing the bar. Anything still held back stays in Background work, and anything that needs a look stays in Library care.

When everything is done, Your library is ready shows how many photos and videos, albums and people were found. Select Start exploring.

Frameleaf also reads every imported file to find identical files and anything Immich had lost track of. Library care shows this as Checking your imported library, with Pause and Resume. Identical files end up stored once, and every merge can be undone. See Identical files.

Immich could lose files while it sorted uploads into folders, so some photos may arrive with only their small preview. The import records what it knows about each one, including where Immich was moving it. Frameleaf then looks for each lost original by its contents: in that spot, in the folders the import used and everywhere else on this server, then in Cloud Backup and on your phones. A copy found in Immich’s folders is copied into your library, and the old one is left where it was. See what was found, and what’s left for you, in Damaged and missing files.

If you still have a copy of a lost photo somewhere else, upload or import it. Frameleaf puts it back under the photo that lost its file, with its albums and details, instead of adding a second photo.

If the import stops or you need to go back

Section titled “If the import stops or you need to go back”

Read the recorded failure, fix its cause and choose Resume safely. Keep Manager’s own folder, both database folders and the media locations as they are, and resume the same import instead of starting a second one into the same destination.

Once Frameleaf has written to your media, restarting Immich against those same files won’t roll it back. To go back, recover Immich from its own database and matching media backup. To move your collection to another application later, use Export your library.

If Manager doesn’t accept your source, you can import an export of your originals instead, or try Frameleaf on the folder without moving anything. A file import brings your photos and videos, but not every account, album or sharing relationship from the original database.