# FAQ

Source: https://frameleaf.app/docs/help/faq/

Quick answers to the questions people ask most, grouped by topic. Can't find yours? Select **Help** at the top of Frameleaf to search every guide or [ask a question](https://frameleaf.app/docs/help/ask-frameleaf/), try [Troubleshooting](https://frameleaf.app/docs/help/troubleshooting/), the [release notes](https://github.com/Frameleaf/frameleaf-app/releases), or search and ask in [GitHub Issues](https://github.com/Frameleaf/frameleaf-app/issues) and [GitHub Discussions](https://github.com/Frameleaf/frameleaf-app/discussions).

## General

### Do I need Frameleaf Cloud?

No. Your photo library runs fully on your own server without a Cloud subscription. Cloud adds remote access, managed backup and GPU services when you want them, each with its own licence, plan and consent. The Apple TV app is the one exception: it needs a Frameleaf account and remote-access entitlement, even on your home network. See [Frameleaf Cloud](https://frameleaf.app/docs/cloud/overview/) and [Apple TV](https://frameleaf.app/docs/apps/apple-tv/).

### Can I view my library on Apple TV?

Yes. The native Apple TV app browses albums, people, places and memories and plays slideshows. Sign in using the QR code or short code shown on the TV. It needs tvOS 26 or later and an eligible server linked to your Frameleaf account. See the [Apple TV guide](https://frameleaf.app/docs/apps/apple-tv/) for controls and settings.

### How do I install the Synology SPK?

Install it from **Package Center → Manual Install**:

1. Download the approved package and checksum from the [Synology guide](https://frameleaf.app/docs/nas/synology/), and verify the checksum.
2. In DSM, choose **Package Center → Manual Install** and select the package.
3. Open Manager from the DSM main menu, at the same HTTPS address as DSM.

Native DSM setup needs no external Manager port and no claim key.

### Where are my photos stored?

On your server, as ordinary files in the **Photos and videos** folder you chose in Frameleaf Manager (`UPLOAD_LOCATION` if you run your own Compose file). Frameleaf adds thumbnails and video previews alongside them, or in a **Thumbnails** folder of their own. Your albums, people and descriptions are in the database, in the **Database** folder (`DB_DATA_LOCATION`). Photos in a [connected folder](https://frameleaf.app/docs/admin/external-libraries/) stay where they are.

### Is Frameleaf open source?

Yes. The Frameleaf Library community edition is open source under AGPLv3 at [github.com/Frameleaf/frameleaf-app](https://github.com/Frameleaf/frameleaf-app).

### Will Frameleaf save me money?

Probably not. There are no monthly fees to run Frameleaf on your own server, but there are other costs: hardware, disks, storage for backups and your own time. There are many good reasons to host your own photos; saving money is rarely one of them.

### Can I bring a library from another photo application?

Yes. Frameleaf Manager imports a whole installation from Immich and Noodle Gallery, and, in Beta, from PhotoPrism, Photoview, PiGallery2, Lychee, Nextcloud, Piwigo, LibrePhotos and Ente Photos, with accounts and albums. Google Photos and iCloud Photos have imports of their own, and any other app works through an export of your originals. Start with [Bring an existing library](https://frameleaf.app/docs/migrate/from-another-library/).

### What does Beta mean for an import from another photo app?

It's new, and it works on a best-effort basis across each app's versions. Photos, videos and albums come across. Manager lists everything that can't before the import starts, and nothing is imported until you agree. If your version of the app hasn't been tested, Manager says so and suggests upgrading it first, but lets you continue. Private photos arrive in Locked, and the other app's own photos and data are never changed. See [Switch from another photo app](https://frameleaf.app/docs/migrate/from-other-photo-apps/).

### Can I try Frameleaf without moving my photos?

Yes. Connect the folder your photos are in, read-only, and Frameleaf shows them where they are while your other app carries on as before. Nothing is moved, copied or changed. See [Try Frameleaf without moving your photos](https://frameleaf.app/docs/migrate/try-without-moving-your-photos/).

### Can I switch from Immich? Is Frameleaf still backward compatible?

Yes, you can switch with a one-time import. Support for Immich backward compatibility ended on **October 15, 2026**, and Frameleaf is now developed independently.

[Switch from Immich](https://frameleaf.app/docs/migrate/from-immich/) uses Frameleaf Manager to import a supported source into a fresh Frameleaf database, with your media staying right where it is. The new Frameleaf system uses PostgreSQL 19 and database-backed job queues, with no Redis to run. The import is a one-time move for supported sources, so plan to settle on Frameleaf: the two applications don't share a database or switch back and forth. Your library opens straight after the import, and a **Setting up your library** bar shows the file check, thumbnails and search as they finish.

### Can I use Frameleaf for client work?

Yes. **Clients** keeps each client's shoots together, [client galleries](https://frameleaf.app/docs/using/client-galleries/) let a client pick favourites, approve the edits and receive the finished photographs, and a [studio website](https://frameleaf.app/docs/using/studio-website/) shows your work and takes enquiries. See [Clients](https://frameleaf.app/docs/using/clients/).

### Can I email a print offer or review request to my clients?

Yes. In **Clients**, open **Email campaigns**, choose an audience and template, then preview and test before sending. Your server needs email delivery and a public address; every campaign includes an unsubscribe link. See [Email campaigns](https://frameleaf.app/docs/using/clients-campaigns/).

### Can clients pay me by card or book a session online?

Yes. In **Clients**, open **Payments** and connect your studio's own Stripe account; payments go straight to you and Frameleaf takes no fee. Then share **Payment links**, or add **Booking types** so clients can choose a session, add extras and pay a deposit from your studio website. See [Payments, payment links and bookings](https://frameleaf.app/docs/using/clients-payments/).

### Can my clients sign a contract online?

Yes. In **Clients**, open **Contracts**, write a template with the client's name, session date and total as merge fields, and send it. The client signs with their typed name or a drawn signature, and you both get a signed PDF with its signing record. Signing happens on your server, with no signing service or fee. See [Contracts](https://frameleaf.app/docs/using/clients-contracts/).

### Can I send invoices with a deposit and take payment online?

Yes. In **Clients**, open **Invoices**, add the line items, tax, deposit and due dates, and send it. With a payment account connected under **Payments**, the client pays the amount due online; Frameleaf takes no fee. Reminders go out before each due date. See [Invoices](https://frameleaf.app/docs/using/clients-invoices/).

### Can I pay for a particular feature to be built?

No. There's no feature sponsorship or bounty scheme, and development priorities aren't for sale. You can suggest features in [GitHub Discussions](https://github.com/Frameleaf/frameleaf-app/discussions).

## Accounts and sign-in

### How do I reset the admin password?

Run this on the server and follow the prompts:

```bash
docker exec -it frameleaf_server frameleaf-admin reset-admin-password
```

See [Server commands](https://frameleaf.app/docs/admin/server-commands/) for the other commands.

### How do I turn on two-step sign-in?

Open **Settings**, then **Your sign-in & privacy**, then **Two-step sign-in**, and select **Turn on…**. You need an authenticator app on your phone, such as Google Authenticator, Microsoft Authenticator or 1Password, and somewhere safe to keep 10 recovery codes. See [Two-step sign-in](https://frameleaf.app/docs/using/two-step-sign-in/).

### I lost my phone. How do I sign in with two-step sign-in on?

Choose **Use a recovery code** on **Enter your code**. No recovery codes either? Ask your server administrator to select **Turn off two-step sign-in…** on your page in **Users**. It's noted in your account history. See [Lost your phone](https://frameleaf.app/docs/using/two-step-sign-in/#lost-your-phone).

### Why do I have to wait after a wrong password?

After 5 wrong passwords in a row, Frameleaf waits 30 seconds before it checks the next one, and doubles the wait with each further wrong password, up to 30 minutes. The right password clears it. It's a wait, never a lock: your password keeps working, and devices already signed in stay signed in. See [Wrong passwords and waits](https://frameleaf.app/docs/admin/sign-in-and-oauth/#wrong-passwords-and-waits).

### Why did I get a "New sign-in" email?

Your account signed in from a device or network your server hasn't seen before. If it was you, there's nothing to do. If not, select **This wasn't me** to sign out devices you don't recognise, then change your password. To stop these emails, turn off **Sign-ins from unfamiliar devices or networks** in **Settings → Notifications → Emails you receive**. See [New sign-in emails](https://frameleaf.app/docs/using/notifications/#new-sign-in-emails).

### How do I see who signed in to my account?

Open **Settings**, then **Your sign-in & privacy**, then **Account activity**. It lists sign-ins, password and two-step changes and sharing, with the device and when. Administrators can see everyone's. See [Account activity](https://frameleaf.app/docs/using/account-activity/).

### How do I see every user on the server?

```bash
docker exec -it frameleaf_server frameleaf-admin list-users
```

Administrators can also see everyone in **Settings**, then **Users**.

### Do I need a setup code for a new server?

No. A new server has no setup code. Anyone on its home network can set it up until it has an administrator, so set it up soon after installing. See [First steps](https://frameleaf.app/docs/start/first-steps/#your-account).

### How do I change my profile picture?

Open a photo, choose the three-dot menu in the top right, then **Set as profile picture**. Zoom with the scroll wheel until the photo fills the circle, drag it into position and choose **Save**.

### Can I show dates day first, or use a 24-hour clock, without changing my language?

Yes. Open **Settings → Your preferences → Look & playback** and choose a **Date format** and a **Time format**. Both follow your region until you change them, and they apply in every browser you sign in to. See [Look & playback](https://frameleaf.app/docs/using/account-settings/#look--playback).

### Can I post a shared photo on a forum or website?

Yes. Share one photo with a link that has no password and allows downloads, then choose **Copy image link**. The address shows the picture itself, with its location removed. See [Copy an image link](https://frameleaf.app/docs/using/sharing/#copy-an-image-link).

### Is there a desktop app?

Yes. [Frameleaf Desktop](https://frameleaf.app/docs/apps/desktop/) runs on Macs with Apple silicon, 64-bit Windows 11 and Linux. It opens your library in its own window, lets your computer help your server with faces, smart search and text recognition, copies photo folders such as OneDrive to your server, and manages your server through Frameleaf Manager. It can also host your whole library with **Run Frameleaf here**. Download it from the [latest release](https://github.com/Frameleaf/frameleaf-desktop/releases/latest).

## Phone apps

### Which phones are supported?

Frameleaf has native apps for iPhone and iPad (iOS 26 or later) and Android (Android 11 or later). Install from the [App Store](https://apps.apple.com/us/app/frameleaf/id6821111014) or [Google Play](https://play.google.com/store/apps/details?id=app.frameleaf.android), or use the web app in your phone's browser. See [iPhone and Android apps](https://frameleaf.app/docs/using/mobile-apps/).

### I can't sign in to the app after an update

Usually the app and server versions don't match. The apps usually work with the current and previous major server version, but the server only works with apps of its own major version, so update your phones before the server. Then check you can sign in on the web app with the same email and password. See [Upgrading](https://frameleaf.app/docs/admin/upgrading/).

### Why does backup stop when I leave the app?

Because your phone's operating system takes over. Backup while the app is open runs straight away; in the background, the operating system decides when tasks run and for how long, usually based on battery-saving rules that differ between manufacturers.

### Background backup on my iPhone rarely runs

That's iOS deciding when apps may run in the background. You can give Frameleaf the best chance:

- Turn on **Background App Refresh** for Frameleaf in **Settings**, then **General**, then **Background App Refresh**.
- Turn off **Low Power Mode** when you don't need it.
- Turn off Background App Refresh for apps that don't need it, so there's less competition.
- Open the app regularly.

See [iPhone and iPad](https://frameleaf.app/docs/apps/iphone/#in-the-background) for the app's own backup options.

### Does Frameleaf work behind a proxy that needs custom headers, mutual TLS, a self-signed certificate or Basic Auth?

Custom headers and client certificates (mutual TLS) work in the iPhone, iPad and Android apps, through each server's connection options. Most people never need them. See [Servers behind a proxy](https://frameleaf.app/docs/apps/iphone/#servers-behind-a-proxy) on iPhone and iPad, [on Android](https://frameleaf.app/docs/apps/android/#servers-behind-a-proxy), and, for administrators, [Give the apps access through your proxy](https://frameleaf.app/docs/admin/reverse-proxy/#give-the-apps-access-through-your-proxy). Elsewhere, and for self-signed certificates and Basic Auth, these setups are experimental and often break video playback, uploads and downloads. For a setup that just works, use a VPN, [Frameleaf Cloud remote access](https://frameleaf.app/docs/cloud/remote-access/), or a free trusted certificate such as one from [Let's Encrypt](https://letsencrypt.org/) instead.

## Files and storage

### Does Frameleaf change my files?

No. Frameleaf never modifies your originals. Changes to metadata (dates, locations, descriptions, ratings, tags) are saved in the database and in an `.xmp` sidecar file next to the original. Edits are saved as separate versions.

Frameleaf **does** delete an original once it's in the trash and the trash is emptied, either by you or automatically after the trash period (30 days by default).

When a photo's file is damaged, Frameleaf repairs it by itself where it can: the repaired copy takes its place in your library and the damaged file is kept beside it, so **Undo** puts it back. Nothing is deleted to fix a file. See [Damaged and missing files](https://frameleaf.app/docs/using/damaged-and-missing-files/).

### Why are my files named with random strings?

With the folder layout off, Frameleaf names stored files with a random identifier (a UUID) so names never clash. To get readable folders and file names, turn on **Sort originals into folders** in **Settings**, then **Storage & originals**, then **Folder layout**, then select **Re-file existing photos…** for the photos you already have. Read [Storage template](https://frameleaf.app/docs/admin/storage-template/) first.

### I changed the storage template. What happens to existing files?

Nothing, until you select **Re-file existing photos…** in **Settings**, then **Storage & originals**, then **Folder layout**. A new layout only applies to new uploads otherwise. Moving never replaces another file, and each old file stays until its new copy is checked. See [Storage template](https://frameleaf.app/docs/admin/storage-template/) and [How files are moved](https://frameleaf.app/docs/admin/storage-template/#how-files-are-moved).

### Why are some files stored under the wrong date?

Files are sorted into folders once, straight after upload, using the date Frameleaf read at the time. If the date couldn't be read then, or you've corrected it since, the file can sit in the wrong folder. Select **Re-file existing photos…** in **Folder layout** to sort them again. If the date itself is wrong, fix it first with [Date & Time Doctor](https://frameleaf.app/docs/using/date-and-time-doctor/).

### Why don't my WhatsApp photos have the right date?

WhatsApp strips the metadata from files it sends, so Frameleaf has no way of knowing when they were taken. You can [change the date](https://frameleaf.app/docs/using/library/) of several items at once, and [Date & Time Doctor](https://frameleaf.app/docs/using/date-and-time-doctor/) finds photos whose dates, time zones or camera clocks look wrong and fixes them with an undo.

### Can I add my existing photo library?

Yes. [Connect the folder](https://frameleaf.app/docs/admin/external-libraries/) to show it without copying it, or upload it from your browser, with Frameleaf Desktop or with the command-line tool. See [Import from a folder](https://frameleaf.app/docs/migrate/from-a-folder/).

### Can I keep my existing album structure when importing?

Yes, with the command-line tool's `--album` option, which creates an album for each folder. See [Import from a folder](https://frameleaf.app/docs/migrate/from-a-folder/). Imports from Google Photos, iCloud Photos and other photo apps bring your albums with them.

### What happens if I import the same photos twice?

Nothing is added twice. Every import recognises a file you already have: the photo isn't copied again, and from Google Photos and iCloud it joins its albums. When the photo you already have has a missing or damaged file, the import puts the good file back under it. See [Bring an existing library](https://frameleaf.app/docs/migrate/from-another-library/#nothing-is-added-twice).

### Is there a folder on the server I can drop an export into?

Yes. Every server has a built-in **Imports** folder, the `imports` folder inside Frameleaf's storage folder. Copy a Google Photos export into it and an administrator can import it from there without uploading. Nothing in it joins your library until you import it. See [Import from a folder on this server](https://frameleaf.app/docs/migrate/google-photos/#advanced-import-from-a-folder-on-this-server).

### What happens if the same photo is in two accounts?

Each account keeps its own photo, with its own albums, faces, favourites and Locked state. On the drive, Frameleaf keeps one file for identical files, by itself, so exact copies take no extra space. When the same file is twice in one person's library, the two photos become one, and the merge can be undone in **Duplicates**. See [Identical files](https://frameleaf.app/docs/admin/physical-deduplication/).

### Can Frameleaf compress my photos during backup?

No. Your originals are always kept exactly as they were uploaded.

### How do I back up Frameleaf?

You need both the database and your files. Frameleaf backs up its database nightly; you back up your photos folder (`UPLOAD_LOCATION`) with a tool of your choice, or with Frameleaf Cloud backup. See [Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/).

### How can I hide a photo from the timeline?

**Archive** it. Archived items leave the timeline and folder view but still appear in search and in the **Archive** view. To hide something properly, behind your PIN, use [Locked](https://frameleaf.app/docs/using/private-content/).

### Does Frameleaf read face tags already in my files?

Yes. It creates faces and people from the face metadata in imported files.

### Can I take my photos out again?

Yes, at any time. Download a selection, or use **Export a copy** in **Settings**, then **Import & export**, for your originals with their albums, edits and details in a package you can check years later. See [Export your library](https://frameleaf.app/docs/migrate/export-your-library/).

### Can I edit RAW photos?

Yes. A RAW photo opens in the RAW editor, with light, colour, tone curve, lens correction and masks. The camera original is never changed. See [RAW editor](https://frameleaf.app/docs/using/raw-develop/) and [RAW files](https://frameleaf.app/docs/help/supported-formats/#raw-files).

### How do I mount a Samba (CIFS) share inside Docker?

If you can't mount the share on the host (on Windows, for example), mount it in Docker. Add a volume to `frameleaf-server` and define it at the bottom of `docker-compose.yml`, changing the user name, password, IP address and share name:

```yaml
services:
  frameleaf-server:
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
      - originals:/usr/src/app/originals

volumes:
  model-cache:
  originals:
    driver_opts:
      type: cifs
      o: "iocharset=utf8,username=USERNAMEHERE,password=PASSWORDHERE,rw" # use ro for read-only
      device: "//localipaddress/sharename"
```

You can name the volume and the path inside the container whatever you like, then add the path as a [folder of photos](https://frameleaf.app/docs/admin/external-libraries/). Never put the database on a network share.

## Videos

### Can I zoom into a video?

Yes. Zoom with the mouse wheel, a pinch or a double-click while the video plays or is paused, and drag to look around. **Fit** puts the whole video back. See [Zoom into a video](https://frameleaf.app/docs/using/library/#zoom-into-a-video).

### Only photos upload, not videos

This usually happens behind a reverse proxy. Make sure your [reverse proxy](https://frameleaf.app/docs/admin/reverse-proxy/) allows large requests, and check its free disk space: some proxies cache uploads to disk first, and the upload fails when the disk fills.

Cloudflare Tunnel has an official upload limit of 100 MB that can't be changed. Larger files sometimes work, but if you have problems, use a different way to reach your server, such as [Frameleaf Cloud remote access](https://frameleaf.app/docs/cloud/remote-access/).

### Why does Frameleaf make lower-quality copies of my videos?

Frameleaf always keeps your original. Alongside it, it creates a transcoded copy that plays smoothly in browsers and on phones. You can play the original from the viewer.

### How do I delete transcoded videos but keep the originals?

Choose a rule that makes them unnecessary, then make the copies again.

1. Go to **Settings**, then **Editing & playback**, then **Video playback copies**, and choose **Which videos get a copy** (or **Rule** under **Advanced: which videos need a copy**).
2. Make the copy again for one video with **Refresh encoded video** or **Transcode video** in the viewer's menu (both do the same), or for every video with **Remake copies**.

For each video, if the rule says it needs a copy, the existing copy is replaced; if not, it's deleted. For example, choosing **Never make copies** and remaking copies for all videos deletes every playback copy. See [Video transcoding](https://frameleaf.app/docs/admin/video-transcoding/).

### HDR videos look pale in the player but fine when downloaded

That's a known issue with how the web player shows HDR colour. Your originals are fine, as the download shows.

## Connected folders

A connected folder is a folder of photos Frameleaf shows where it is, without copying. Older guides call these external libraries.

### Are duplicates detected in connected folders?

Files in connected folders are never moved, linked or merged, so the same file can appear twice in the timeline when it's in two folders, or in a folder and in your uploads. Use [duplicate review](https://frameleaf.app/docs/using/duplicates/) to find them and keep the best copy.

### Can I edit details of photos in a read-only folder?

Yes. In a read-only folder, Frameleaf keeps your changes to dates, locations, descriptions and ratings in its own storage instead of beside the originals. A folder Frameleaf can't write to, such as one mounted with `:ro`, is treated as read-only by itself.

### What happens when I delete photos from a connected folder?

Frameleaf never deletes the original file. Deleting a photo removes it from Frameleaf when the trash is emptied, but the file is still in the folder, so the next check brings it back. To keep a photo out of sight, archive it instead. See [Try Frameleaf without moving your photos](https://frameleaf.app/docs/migrate/try-without-moving-your-photos/).

## Machine learning

### Does face recognition use the cloud?

Only if your administrator chooses it, and only for people who allow it. Faces and smart search run on your own server or a computer at home by default, even with Frameleaf Cloud linked. An administrator can choose Frameleaf Cloud for them under **Where work runs** on the **Computers** page. The Cloud then finds faces with the same model your server uses, but grouping faces into people and naming them happen only on your server. Text recognition always runs at home. See [Search and faces on Frameleaf Cloud](https://frameleaf.app/docs/admin/workers/#search-and-faces-on-frameleaf-cloud).

### Can I keep my own photos off Frameleaf Cloud?

Yes. Open **Settings**, then **Your preferences**, then **Where your photos are processed**, and choose **Only at home**. AI work on your photos then runs on this server or a computer at home, whatever the administrator chose, and only you can change it. Photos you share keep your choice. See [Choose where processing runs](https://frameleaf.app/docs/help/choose-processing/#each-persons-choice).

### How does smart search work?

Frameleaf uses CLIP models. A model turns each image into an embedding, a list of numbers that captures what's in it. Your search text is turned into an embedding the same way, and Frameleaf finds images whose embeddings are closest. Smart search doesn't create visible tags or descriptions; [AI descriptions](https://frameleaf.app/docs/using/ai-descriptions/) are a separate, optional feature.

### Can I search in languages other than English?

Yes, with a multilingual search model. An administrator opens **Settings**, then **Search & intelligence**, then **Visual search**, then **Advanced: use your own model**, and enters the model's name from Hugging Face. Saving reads the whole library again by itself, now or tonight. See [Search models](https://frameleaf.app/docs/using/search-models/#use-a-model-of-your-own).

### Can I use my own CLIP model?

Yes. The **Search quality** slider in **Visual search** shows the models Frameleaf publishes, from quickest to best. To use another, an administrator enters its Hugging Face name under **Advanced: use your own model**. Frameleaf checks the model's files before anything is read again, and refuses one it can't load. See [Search models](https://frameleaf.app/docs/using/search-models/).

### Does face recognition work on videos?

Only on the video's thumbnail. A face visible there is recognised; faces elsewhere in the video aren't.

### Why aren't my archived photos on a person's page?

People leaves archived photos out by default. Turn on **Include archived photos** under **Settings → Your preferences → Tools & sidebar → People options** to show and count them. See [Archived photos in People](https://frameleaf.app/docs/using/people/#archived-photos-in-people).

### Does Frameleaf recognise animals?

Yes, cats and dogs, as [pets](https://frameleaf.app/docs/using/people/#pets) with their own profiles. Pet recognition is optional and needs an administrator to install its model. Smart search also finds animals by description, such as "golden retriever".

### I get "faces" that aren't faces

Raise **Face clarity needed** in **Settings**, then **Search & intelligence**, then **Faces & identity**, then **Advanced: face model and numbers**, for example to 0.8. Going above 0.9 can miss real faces. To stop odd thumbnails being chosen for a person, raise **Photos needed before someone appears**. See [People and pets](https://frameleaf.app/docs/using/people/#for-administrators).

### How do I turn off machine learning?

Go to **Settings**, then **Search & intelligence**. You can turn it all off with **Search and recognition**, or turn off single features, for example keeping face recognition but turning off smart search. Search and Explore work poorly without it.

Turning every feature off doesn't stop the machine learning container. To stop it from starting at all, comment out the `frameleaf-machine-learning` service in `docker-compose.yml`.

### Models are corrupt or won't download

Find the model name and the failed download in the machine learning log, then check the server can reach the model source and the cache has free space. See [Model sources](https://frameleaf.app/docs/admin/environment-variables/#where-models-come-from).

To replace a damaged model, stop machine learning, remove just that model's files from your installation's `/cache` mount, then restart and let it download again. Your library volume stays untouched.

### The model cache takes up a lot of space

That's because downloaded models stay cached even after they're unloaded from memory. To free space, stop the machine learning container and remove the models you no longer use. Keep any your offline installation needs.

## Performance

### Frameleaf is slow on a Raspberry Pi or other low-memory system

Transcoding and machine learning can be too heavy for small machines. [Lower the CPU and memory use](#can-i-lower-cpu-and-memory-use), let a [more powerful computer at home](https://frameleaf.app/docs/help/choose-processing/) do the heavy work, or turn machine learning off.

### Can I lower CPU and memory use?

Yes. The first big upload is the busiest time, because so many jobs run at once. Transcoding and machine learning (smart search, face detection) use the most CPU, then thumbnails. To lower it:

- Set **How hard this server works** to **Light**, in **Settings**, then **Computers & background work**, then **Background work**. See [Jobs](https://frameleaf.app/docs/admin/jobs/#concurrency).
- Set **When heavy work runs** to **Overnight**, on the same page, so the heavy work waits for the night.
- In the video transcoding settings, set **Threads** to 1 or 2.
- Move the **Recognition quality** slider in **Faces & identity** to a smaller model, such as `buffalo_s`. It's faster but less accurate. Frameleaf looks for faces again by itself when you save.
- Move the **Search quality** slider in **Visual search** to a lighter model. See [Search models](https://frameleaf.app/docs/using/search-models/).
- Let another computer do the heavy work. A computer at home running [Frameleaf Desktop](https://frameleaf.app/docs/apps/desktop/), or Frameleaf Cloud, can take it on. See [Choose where processing runs](https://frameleaf.app/docs/help/choose-processing/).
- Limit the containers' resources (below), after trying the steps above.

### Can I limit CPU and memory use?

Yes. By default a container can use as much as the host allows. Add this to any service in `docker-compose.yml`:

```yaml
deploy:
  resources:
    limits:
      # Number of CPU threads
      cpus: "1.00"
      # Gigabytes of memory
      memory: "1G"
```

A memory limit works by stopping the container when it's exceeded, so a limit that's too low makes Frameleaf unstable. Give the database at least 2 GB. See Docker's [resource constraints](https://docs.docker.com/config/containers/resource_constraints/).

### How can I make machine learning faster?

Set **How hard this server works** to **Fast** in **Background work**, or raise **Jobs running at once**, so more items are processed in parallel. This speeds up processing, not searching itself.

:::caution
On an ordinary CPU, 2 or 3 concurrent jobs can already use the whole processor, and disk speed soon becomes the limit, especially on hard drives. With a GPU you can go higher, but rarely above 16.
:::

A GPU makes the biggest difference. See [Hardware acceleration](https://frameleaf.app/docs/admin/hardware-acceleration/). A computer at home with a graphics card can help too, through [Frameleaf Desktop](https://frameleaf.app/docs/apps/desktop/); see [Choose where processing runs](https://frameleaf.app/docs/help/choose-processing/).

### The web app says "Server Status Offline" and "Version Unknown"

Usually your reverse proxy isn't forwarding WebSockets. Check you can reach the server and look for errors in the browser's network tab. If pages load but live updates don't, turn on WebSocket support in the proxy. See [Reverse proxy](https://frameleaf.app/docs/admin/reverse-proxy/).

## Docker and the server

### How do I see Frameleaf's logs?

```bash
docker logs frameleaf_server
docker logs frameleaf_machine_learning
```

Add `--follow` to keep watching new lines. See [Troubleshooting](https://frameleaf.app/docs/help/troubleshooting/#useful-docker-commands).

### Can I run Frameleaf as a non-root user?

Yes. Use the release's `docker-compose.rootless.yml`, or set `user` on each service. See [Run as a non-root user](https://frameleaf.app/docs/start/other-install-methods/#containers-running-as-a-non-root-user).

### The machine learning service says workers are crashing

It depends on the message. If a worker is **exiting**, that's normal: idle workers shut down to save memory.

- **SIGKILL** or exit code **137**: the process was killed. Check the host for an out-of-memory event or an administrator stop, then adjust memory limits if needed.
- **SIGILL** or exit code **132**: your CPU doesn't support the instructions the service needs. See [Requirements](https://frameleaf.app/docs/start/requirements/#hardware).

### How do I wipe Frameleaf and start again?

:::danger
This deletes your database and every uploaded file. You start from scratch.
:::

```bash
docker compose down -v
```

Then delete the `DB_DATA_LOCATION` folder (the database and settings) and the `UPLOAD_LOCATION` folder (every uploaded file). The next `docker compose up -d` is a fresh installation.

With Portainer, bring the stack down, remove every Frameleaf volume in the **Volumes** section, then delete the same two folders.

## Database

### I get "data directory has wrong ownership" errors

Your database folder is on a filesystem that doesn't support Unix ownership, such as NTFS or exFAT, or on a network share. See [Requirements](https://frameleaf.app/docs/start/requirements/#windows).

### How do I check the database for corruption?

See [Check the database for corruption](https://frameleaf.app/docs/help/troubleshooting/#check-the-database-for-corruption).

### Should I upgrade Postgres to a newer major version?

No. Use the Postgres image in the release's `docker-compose.yml`. A major Postgres upgrade takes more than changing the image tag. See [Database](https://frameleaf.app/docs/admin/database/).

## Privacy

### Can Frameleaf hide sensitive photos?

Yes. [Locked](https://frameleaf.app/docs/using/private-content/) items stay in your albums but are hidden everywhere until you unlock with your PIN. Optional sensitive-content detection can flag items for your private review; hiding uses that private flag, not a visible tag, and album membership is kept.

### Does Frameleaf send data anywhere?

No telemetry, ever. During setup you choose whether to load map tiles and check for updates, and every other outside call Frameleaf doesn't need stays off. Machine learning models are downloaded from the Frameleaf model mirror. Help articles are fetched from frameleaf.app and kept on your server, and a question you type into Ask Frameleaf goes to frameleaf.app's Ask service; an administrator can turn Ask off. Frameleaf Cloud features only work once you link a server and turn them on, and each person can keep AI work on their own photos at home. See [Environment variables](https://frameleaf.app/docs/admin/environment-variables/#no-telemetry) and [Ask Frameleaf](https://frameleaf.app/docs/help/ask-frameleaf/#what-is-sent-when-you-ask).

## Photographer workflows

### Can Frameleaf read edits saved by Lightroom or darktable?

Yes, supported XMP settings create an approximate, inactive [Develop version](https://frameleaf.app/docs/using/editing/#edits-from-lightroom-and-darktable). Your original and Current version stay unchanged. This does not install a Lightroom publishing plugin.

### Can guests find themselves in a client gallery?

Yes, when the photographer enables selfie search. Guests choose **Find my photos**, consent to the one-time search and supply a selfie. Results stay within their gallery. See [Client galleries](https://frameleaf.app/docs/using/clients-galleries/#let-guests-find-their-photos).
