External libraries

An external library shows photos and videos that live in a folder outside Frameleaf, such as an existing archive on your NAS. Frameleaf scans the folder and adds what it finds to the owner’s timeline. The files stay where they are, and they look and behave like any other photo: they appear on the map, can go in albums, and so on.

Managing external libraries needs an administrator account. Each library belongs to one person, chosen when you create it.

1. Mount the folder

Frameleaf runs in Docker, so first make the folder visible inside the container. In docker-compose.yml, add a line under volumes: in the immich-server service:

services:
  immich-server:
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /home/user/old-pics:/mnt/media/old-pics:ro
      - /mnt/nas/christmas-trip:/mnt/media/christmas-trip:ro
      - "C:/Users/me/Desktop/my media:/mnt/media/my-media:ro" # a folder on Windows

The part before the colon is the folder on your computer; the part after is where the container sees it. The :ro at the end makes the folder read-only to Frameleaf. Remove it only if you want Frameleaf to be able to delete files there or write XMP sidecar files next to them.

Then run docker compose up -d. If you run separate worker containers, mount the same folders there too.

2. Create the library

1. Select Settings in the sidebar to open the Command Center, then open Libraries.
2. Select Add external library.
3. Enter a Library name and choose the Owner. Ownership is fixed after the library is created.
4. Under Import folders, select Add folder and enter the folder as the container sees it, for example /mnt/media/old-pics, not /home/user/old-pics.
5. Optionally add Exclusion patterns (see below).
6. Select Create library. Saving doesn’t start a scan.
7. Select the library in the list, then select Scan library.

Each folder is checked as you add it. Frameleaf tells you if it doesn’t exist, can’t be read, is a file rather than a folder, is inside Frameleaf’s own upload folder, is inside another import folder of the same library, or is already imported by another library. Use absolute paths.

To check that it’s working, open Settings, then Compute & jobs. You should see jobs for the library scan, thumbnails and metadata. The library’s own page shows the scan’s progress, and you can Cancel scan.

A library can have up to 128 import folders and 128 exclusion patterns. Folders are scanned including subfolders, and a file in more than one folder is only added once.

Example: two libraries

Say you want to add childhood photos, a Christmas trip whose Raw subfolder holds camera RAW files you don’t want, and videos from the same trip.

• Create a library called “Christmas Trip” with the import folder /mnt/media/christmas-trip and the exclusion pattern **/Raw/**, then scan it.
• Create a second library called “Old videos and photos” with the import folders /mnt/media/old-pics and /mnt/media/videos, then scan it.

You could put all three folders in one library, as long as nothing in the other folders matches the Raw exclusion.

Leave files out

By default every file in the import folders is added. To skip some, add exclusion patterns. They match the full file path:

Pattern	Leaves out
**/*.tif	Every .tif file
**/hidden.jpg	Every file named hidden.jpg
**/Raw/**	Everything in any folder named Raw, including its subfolders
**/*.{tif,jpg}	Every .tif and .jpg file
**/\@eaDir/**	Everything in any folder named @eaDir

* matches within one file or folder name, and ** matches any number of subfolders. Escape special characters such as @ with a backslash. Keep patterns simple; advanced patterns may not work reliably.

Saving new folders or exclusions stops a scan that’s in progress. Scan again afterwards.

Keep the library up to date

Frameleaf doesn’t see changes to an external folder until it scans it again.

• Nightly scan. Every library is scanned once a day, at midnight by default. This also finishes removing any library whose removal was interrupted.
• Change the schedule. Open Settings, then Libraries, then External Library. Under Periodic Scanning, keep Enable periodic library scanning on and choose one of the Cron expression presets, or enter your own Cron expression, for example 0 0 * * * for every night at midnight.
• Scan everything now. In Libraries, select the button that scans them all, for example Scan 3 libraries.
• Library watching [EXPERIMENTAL] imports new and changed files as soon as the operating system reports them, without a rescan. It’s for advanced users and usually doesn’t work for folders on a network drive.

If watching fails

If the log shows an ENOSPC error, the system has run out of file watchers. Raise fs.inotify.max_user_watches (8192 by default) in sysctl to more than the number of files in your import folders, including excluded ones.

In rare cases the watcher can hang and stop Frameleaf from starting. Turn watching off in the config file (library.watch.enabled), or start the server without its background workers, turn off watching in the Command Center, then start normally again.

Things to know

• Deleted files go to the trash. If a file is deleted from disk, the next scan moves it to Frameleaf’s trash. To get it back, restore the original file. After 30 days it’s removed from the trash.
• A folder that disappears isn’t treated as deleted. If an import folder comes back empty or can’t be read while photos are still indexed from it, nothing is marked missing. Reconnect it and scan again.
• Your changes stay in Frameleaf. Albums, descriptions and other details you add are stored in Frameleaf, not in the file. If you move a file to a different place in the folder, Frameleaf treats it as a new photo and those details are lost.
• Edits outside Frameleaf show up after a rescan, but your browser may keep showing the old thumbnail for a while. Clearing the browser cache fixes it.
• Removing a folder from the library removes its photos from Frameleaf, the same as deleting them. Put the folder back and they’re added again as new photos.
• Removing a library removes all of its photos from Frameleaf, along with their faces and their places in albums and shared links. You’re shown what will go and asked to type the library’s name. The files in your folders stay where they are.
• External libraries don’t count towards storage quotas, and the storage template and physical deduplication never move their files.
• Folder view lets you browse a library like a file explorer. Turn it on in Settings, then Your preferences, then Library features, then Enable folders.

If a scan finds nothing

Check that:

• the volume is mounted correctly in docker-compose.yml, and in any worker containers
• the import folder matches the path inside the container, not on the host
• you’re not relying on symlinks, or links across Docker mounts
• the file permissions let Frameleaf read the folder
• you use forward slashes (/), not backslashes

To look from inside the container, run this from your Compose folder, then ls /your/import/path:

docker compose exec immich-server bash