Try Frameleaf without moving your photos
Already keep your photos in another app, or in folders you look after yourself? You can try Frameleaf on them without moving anything. Frameleaf reads the folder where it is, read-only, while your other app carries on as before. Nothing is moved, copied, renamed or deleted, and you can stop whenever you like.
This guide sets up a new library with Frameleaf Manager on Linux, Unraid or TrueNAS, then adds your folder.
How your photos stay safe
Section titled “How your photos stay safe”Two settings work together, and this guide turns on both:
- Manager gives Frameleaf the folder read-only. Frameleaf can look at the files but can’t change them.
- Frameleaf keeps the folder read-only too. Albums, descriptions, dates, ratings and other edits are saved in Frameleaf’s own storage, never beside your originals.
Frameleaf still needs folders of its own, which Manager creates during setup. Here’s what lives where:
- In your folder: your original photos and videos, and any sidecar files your other app writes. They stay untouched.
- In Frameleaf’s folders: thumbnails and video previews, albums, people, descriptions and other edits, photos uploaded from the Frameleaf app, and the database and its backups.
Before you start
Section titled “Before you start”- Find your folder’s path on the server, such as
/mnt/user/photoson Unraid,/mnt/tank/photoson TrueNAS or/media/disk2/Photoson Linux. Use the real folder, not a link (symlink) to it. Its name can’t contain a comma or colon. - Choose the folder of originals only. If your other app keeps its own previews in the same place, pick the folder of originals inside it, or Frameleaf shows those previews as photos too. For an Immich library, that’s the
libraryoruploadfolder inside Immich’s upload location, notthumbsorencoded-video. - Leave room for Frameleaf’s own files, mostly thumbnails and video previews, on a drive with space to spare.
1. Let Manager see the folder
Section titled “1. Let Manager see the folder”On Unraid and TrueNAS, there’s nothing to do. Manager can already see every folder under /mnt. Skip to step 2.
On Linux, Manager can see its parent folder (/srv/frameleaf unless you chose another) and any drives you list in MANAGER_EXTRA_FOLDERS. If your photos are somewhere else, list the folder that holds your photo folder. For photos in /media/disk2/Photos, list /media/disk2:
MANAGER_EXTRA_FOLDERS=/media/disk2 sh launch.sh \ ghcr.io/frameleaf/frameleaf-manager:latest \ 'https://server.example:2282' \ /srv/frameleaf \ '<server-lan-ip>'For photos in /home/sam/Pictures, list /home/sam. Each folder you list must already exist and be at least two levels deep. To list several, separate them with colons. See Add more drives.
Is Manager already running? Remove its container with docker rm --force frameleaf-manager, then run the launcher again with the same arguments and MANAGER_EXTRA_FOLDERS. Manager’s settings stay in the parent folder, and your photo library keeps running while Manager restarts.
2. Set up Frameleaf in Manager
Section titled “2. Set up Frameleaf in Manager”Follow Install with Frameleaf Manager up to Choose how to begin, then:
- Under Set up a new library, select Set up Frameleaf. If Manager also offers Review import for an Immich installation, or lists your app under Import from another photo app, leave it for now: an import brings the whole library into Frameleaf, and an Immich import keeps Immich stopped afterwards.
- For Photos and videos, keep the new folder Manager suggests. This is Frameleaf’s own folder, for thumbnails and phone uploads. Don’t choose your photo folder here.
- Keep or change the Database, Thumbnails and Backups folders as you like.
- Under External folders, select Add a folder…. Open your photo folder and select Use this folder. It’s added with Read-only ticked. Leave it ticked. Add more folders the same way.
- Select Check this server. If another app already uses port
2283, select Use port 2284. Then select Review installation and Install Frameleaf.
Manager won’t add a folder that holds Frameleaf’s own data or sits inside it, or one at the top of a drive, pool or share list, such as /mnt/user. It tells you why and you can choose another.
Already installed Frameleaf?
Section titled “Already installed Frameleaf?”Open Services in Manager. Under External folders, select Add a folder…, choose the folder, then select Save and restart Frameleaf. Photo access pauses for about a minute while Frameleaf restarts.
3. Finish setup
Section titled “3. Finish setup”Carry on with Make it yours to create your photo account and get the app, as in Install with Frameleaf Manager. Anything you upload from your phone goes into Frameleaf’s own Photos and videos folder, never into your photo folder.
4. Add the folder in Frameleaf
Section titled “4. Add the folder in Frameleaf”Sign in to Frameleaf as the administrator. Open Settings, then Libraries, and select Add a folder of photos.
- Select Choose folder…, open the same folder you added in Manager, and select Use this folder. Frameleaf sees it at the same path as the server does, such as
/media/disk2/Photos. Give it a Library name. Only folders connected to Frameleaf are listed. If you see Frameleaf can’t see any folders here yet, or This folder isn’t connected to Frameleaf yet, go back to step 2 and add the folder in Manager, then choose it again. - Under Show these photos in, choose your own account.
- Leave both choices under What to skip ticked. If your other app keeps exports or previews inside the folder, skip them with a pattern such as
**/Exports/**. - Leave Keep source files read-only on. You can’t change it after the folder is added.
- Leave Look for photos as soon as I add it on, and select Add folder.
The first check starts by itself, and you can follow it on the Libraries page. After that, Frameleaf builds thumbnails, faces and search in the background. On a big library this takes a while; follow it in Activity.
For every option on this page, see Folders of photos.
Using Frameleaf alongside your other app
Section titled “Using Frameleaf alongside your other app”- Keep managing your photos the way you do now. Frameleaf finds new, changed and removed files when it checks the folder: every night, or when you select Check now in Libraries. For a folder on this server’s own disks, turn on Notice new files right away and new photos appear within a minute.
- Moving or renaming a file is a new photo to Frameleaf. Albums, descriptions and other details you added in Frameleaf stay with the old one and are lost. Try Frameleaf’s albums on photos you aren’t about to reorganise.
- Albums and people from your other app don’t come across. Frameleaf reads what’s in the files: dates, places, camera details, and the descriptions, ratings and tags in any
.xmpsidecars beside them. To bring a whole library across with its albums, see Bring an existing library, Switch from Immich or Switch from another photo app. - Browse it like your folders. Turn on folder view in Settings, then Your preferences, then Tools & sidebar, with Use in the Folders row.
What Frameleaf never does to your folder
Section titled “What Frameleaf never does to your folder”- It never deletes a file there, not even when you empty the Trash. Deleting a photo in Frameleaf only removes it from Frameleaf. The file is still in your folder, so the next check brings it back. To keep a photo out of sight, archive it instead.
- It never writes your edits there. They’re kept in Frameleaf. Sidecars your other app wrote are still read; Frameleaf edits a copy of its own.
- It never moves or renames files there. The storage template and physical deduplication leave these folders alone.
- It doesn’t panic when the folder goes away. If a file disappears, its photo waits in the Trash and comes back when the file returns. If a NAS is off and the folder looks empty, nothing is marked missing.
Frameleaf’s backups cover its database and its own files, not your folder. Keep backing up your photos the way you do now.
Stop the trial
Section titled “Stop the trial”To take the photos out of Frameleaf, open Settings, then Libraries, select the folder, then Remove N photos from Frameleaf. Select Remove library, then type the library name to confirm. The files stay exactly where they are.
To remove Frameleaf from the server too:
-
In Manager, open Services and note the name after Frameleaf ·, such as
frameleaf-1a2b3c4d5e6f. Select Stop stack. -
Remove the library’s containers, using that name:
Terminal window docker compose -p frameleaf-1a2b3c4d5e6f down -
Remove Manager: on Unraid from the Docker tab, on TrueNAS from Apps, or on Linux with
docker rm --force frameleaf-manager. -
Delete the folders you chose for Frameleaf in step 2: Photos and videos, Database, Thumbnails if it had its own, Backups, and the
managerfolder Manager kept its settings in. Don’t delete a whole drive or parent folder, in case your photo folder is inside it.
Decided to stay? Leave everything as it is. Your folder keeps working this way for good, and you can bring a whole library across later.
If a check finds nothing
Section titled “If a check finds nothing”Make sure that:
- the folder is listed under External folders in Manager’s Services page
- you chose the same path in Frameleaf as in Manager
- Frameleaf is allowed to read the files in the folder
For more checks, see If a check finds nothing.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.