# Folders of photos

Source: https://frameleaf.app/docs/admin/external-libraries/

Frameleaf shows the photos in a folder that is already on this server or a NAS, without moving or copying them.

Already have years of photos in folders? Add the folder, and its photos appear in someone's library. They behave like any other photo: they show on the map, go in albums and can be shared. The files stay where they are. (Older guides call these external libraries.)

You need an administrator account to add a folder. Trying Frameleaf on photos another app looks after? [Try Frameleaf without moving your photos](https://frameleaf.app/docs/migrate/try-without-moving-your-photos/) covers Manager and the server end to end.

## 1. Let Frameleaf see the folder

Frameleaf only sees the folders you connect to it.

**With Frameleaf Manager** (Unraid, TrueNAS and Docker installs set up by Manager), open [Frameleaf Manager](https://frameleaf.app/docs/admin/manager/) and add the folder under **External folders**. Frameleaf restarts for a moment, and the folder can then be chosen in step 2. Nothing needs editing by hand.

**With your own Compose file**, make the folder visible inside the container. In `docker-compose.yml`, add a line under `volumes:` in the `frameleaf-server` service:

```yaml
services:
  frameleaf-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 it is where Frameleaf sees it. The `:ro` at the end makes the folder read-only to Frameleaf, which is the safest choice.

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

## 2. Add the folder

Open **Settings**, then **Libraries**, and select **Add a folder of photos**. The page has four steps.

### 1. Choose the folder

Select **Choose folder…** to browse what this server can see. Open the folder you want, then select **Use this folder**. Frameleaf tells you roughly how many photos and videos it found.

Only folders connected to Frameleaf are listed. If the list is empty on a Manager install, the page says **Frameleaf can’t see any folders here yet** and links to Manager, where you add the folder under **External folders**. If you type a path that isn't connected, it says **This folder isn’t connected to Frameleaf yet**.

If you'd rather type it, open **Advanced: type a path**, enter the **Path on this server**, then select **Use this path**. Use the path Frameleaf sees, such as `/mnt/media/old-pics`, not the one on your computer.

Give the folder a **Library name**, such as "Family photos".

### 2. Whose library

Under **Show these photos in**, choose a person, for example "Sam's library". The photos appear beside Sam's own uploads, and Sam can put them in albums and share them.

A folder belongs to one account, for good. You can't move it to someone else later.

### 3. What to skip

Folders often hold things that aren't your photos. Two choices are ticked for you:

- **Hidden and system files (recommended)**, such as the small previews a computer or NAS leaves behind.
- **Recycle bins, snapshots and NAS thumbnail folders (recommended)**, such as deleted files and old versions a NAS keeps inside the folder.

To skip more, open **Advanced: the patterns these stand for** and add **More patterns, one on each line**. Skipped files are never changed or deleted.

| Pattern | Skips |
| --- | --- |
| `**/*.tif` | Every `.tif` file |
| `**/Raw/**` | Everything in any folder named `Raw` |
| `**/*.{tif,jpg}` | Every `.tif` and `.jpg` file |

One star means any name. Two stars mean any folders.

**Keep source files read-only** is on. Frameleaf then never changes the original files; your edits are kept in Frameleaf instead. You can't change this after the folder is added.

### 4. The first check

**Look for photos as soon as I add it** is on. The first check starts by itself, and you can follow it on the **Libraries** page. If you turn it off, nothing appears until you select **Check now** or the nightly check runs.

Select **Add folder**.

## Keeping folders up to date

Frameleaf only sees new, changed and removed files when it checks a folder.

- **Check a folder now.** In **Libraries**, select the folder, then **Check now**. **Check every file again** looks at every file, not just the new ones.
- **Check them all now.** In **Libraries**, select the button that checks every folder, for example **Check 1 folder now** or **Check 3 folders now**.
- **Every night.** Open **Settings**, then **Libraries**, and find **Keeping folders up to date**. **Check every folder each night** is on. It **Runs in the overnight schedule**, after backups, so they never compete for the disk. To change the time, open **Overnight schedule**.
- **Notice new files right away.** Turn this on, and a photo saved into a folder shows up within a minute. It works for folders on this server's own disks, not network drives. It's still being tested.

### If noticing new files stops working

If the log shows an `ENOSPC` error, the system has run out of file watchers. Raise `fs.inotify.max_user_watches` in sysctl to more than the number of files in your folders.

If it ever stops Frameleaf from starting, turn it off in the [config file](https://frameleaf.app/docs/admin/config-file/) (`library.watch.enabled`).

## A check is not a backup

If a file disappears from a folder, its photo waits in the Trash here and comes back when the file returns. Frameleaf does not back up these folders.

- **A missing file goes to the Trash.** Put the file back and the photo returns. After 30 days in the Trash it's removed from Frameleaf. The file itself is never touched.
- **A folder that can't be reached isn't treated as empty.** If a NAS is off or a folder comes back empty, nothing is marked missing. Reconnect it and check again.
- **Back up the folders yourself.** Frameleaf's own backups cover what it stores, not these folders.

## Things to know

- **Your changes stay in Frameleaf.** Albums, descriptions and other details you add are kept 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 made outside Frameleaf** show up after the next check. Your browser may show the old thumbnail for a while.
- **Folders don't count towards [storage limits](https://frameleaf.app/docs/admin/users/#storage-quotas)**, and the [storage template](https://frameleaf.app/docs/admin/storage-template/) and [identical files](https://frameleaf.app/docs/admin/physical-deduplication/) never move, link or merge their files.
- **Folder view** lets you browse a library like a file explorer. Turn it on in **Settings**, then **Your preferences**, then **Tools & sidebar**, with **Use** in the **Folders** row.

## The Imports folder is something else

Every server also has a built-in **Imports** folder, inside its own storage. It's a drop-off point for an export you want to bring in, such as a [Google Photos export](https://frameleaf.app/docs/migrate/google-photos/) that's already on the server, so it doesn't need uploading. Nothing in Imports appears in a library by itself, the nightly folder check doesn't look there, and it isn't a folder of photos in the sense of this page. An import copies what it reads into Frameleaf's own storage.

## Remove a folder

In **Libraries**, select the folder, then **Remove N photos from Frameleaf** (for example, **Remove 1,240 photos from Frameleaf**). You see what goes with it: faces, places in albums and shared links. Select **Remove library**, then **Type the library name to confirm**.

The photos leave Frameleaf. The original files are kept on disk, where they were.

## If a check finds nothing

Check that:

- the folder is mounted in `docker-compose.yml`, and in any worker containers
- you chose the path Frameleaf sees, not the one on your computer
- you're not relying on links (symlinks), or links across Docker mounts
- Frameleaf is allowed to read the folder
- you use forward slashes (`/`), not backslashes

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

```bash
docker exec frameleaf_server bash
```
