FAQ

Can’t find your answer here? Try Troubleshooting, the release notes, or search and ask in GitHub Issues and GitHub Discussions.

General

Do I need Frameleaf Cloud?

No. Everything on your server works without an account, a licence or an internet connection. Frameleaf Cloud adds remote access, off-site backup and cloud GPU processing if you want them. See Frameleaf Cloud.

Where are my photos stored?

On your server, as ordinary files in the folder you set as UPLOAD_LOCATION. Frameleaf adds thumbnails and video previews alongside them. Your albums, people and descriptions are in the database, in DB_DATA_LOCATION.

Is Frameleaf open source?

The Frameleaf Library community edition is open source under AGPLv3 at 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.

I already run Immich. Can I switch?

Yes. Frameleaf keeps the same Compose service names and still accepts the old IMMICH_* variable names, so an existing installation keeps its database and media paths. Read the release notes and back up first. See Moving from Immich.

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.

Accounts and sign-in

How do I reset the admin password?

Run this on the server and follow the prompts:

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

See Server commands for the other commands.

How do I see every user on the server?

docker exec -it frameleaf_server frameleaf-admin list-users

Administrators can also see everyone in Settings, then Users.

I lost the setup code for my new server

It’s printed in the server’s log every time it starts, and you can print it at any time until the server has an administrator:

docker exec -it frameleaf_server frameleaf-admin setup-code

It only works from your home network. See First steps.

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.

Phone apps

Which phones are supported?

Frameleaf has native apps for iPhone and iPad (iOS 26 or later) and Android (Android 11 or later). They’re coming soon to the App Store and Google Play; until then, use the web app in your phone’s browser. See iPhone and Android apps.

I can’t sign in to the app after an update

Make sure the app and the server are on compatible versions. 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.

Why does backup stop when I leave the app?

Backup while the app is open and backup in the background are separate. When you leave the app, your phone’s operating system decides when background tasks run and for how long, usually based on battery-saving rules. That differs between manufacturers.

Background backup on my iPhone rarely runs

iOS decides when apps may run in the background, and the app has little control over it. To give it 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 for the app’s own backup options.

Features don’t work with a self-signed certificate, Basic Auth, custom headers or mutual TLS

These network options are experimental and often break video playback, uploads and downloads. Use a VPN, Frameleaf Cloud remote access, or a free trusted certificate such as one from Let’s Encrypt 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).

Why are my files named with random strings?

With the storage template off, Frameleaf names stored files with a random identifier (a UUID) so names never clash. To get readable folders and file names, turn on the storage template and run the Storage Template Migration job. Read Storage template first.

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

Nothing, until you run the Storage Template Migration job from the jobs page. A new template only applies to new uploads otherwise. See Storage template.

Why are some files stored under the wrong date?

The storage template job runs automatically only once per item, after upload. If metadata extraction failed or the job was cancelled or cleared at the time, the file can end up in the wrong folder. Run the Storage Template Migration job again.

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 of several items at once.

Can I add my existing photo library?

Yes. Use an external library to show an existing folder without copying it, or upload it with the command-line tool. See Import 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.

What happens if the same photo is in two accounts?

Each account gets its own item, with its own albums, faces and thumbnails. Files don’t have to be unique across users. To store the bytes only once, an administrator can turn on physical deduplication, which keeps each person’s items, albums and permissions separate.

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 UPLOAD_LOCATION with a tool of your choice. See 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.

Does Frameleaf read face tags already in my files?

Yes. It creates faces and people from the face metadata in imported 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 immich-server and define it at the bottom of docker-compose.yml, changing the user name, password, IP address and share name:

services:
  immich-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 an external library. Never put the database on a network share.

Videos

Only photos upload, not videos

This usually happens behind a reverse proxy. Make sure your 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.

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?

Set a transcoding policy that makes them unnecessary, then rerun transcoding.

1. Go to Administration, then Settings, then Video Transcoding, and choose a Transcode policy.
2. Run transcoding for one video with Refresh encoded videos in the viewer’s menu, or for every video from the jobs page.

For each video, if the policy says it should be transcoded, the existing copy is overwritten; if not, it’s deleted. For example, setting the policy to Don’t transcode any videos and running transcoding for all videos deletes every transcoded copy. See Video transcoding.

HDR videos look pale in the player but fine when downloaded

The web player has known problems showing HDR colour. Downloaded originals aren’t affected.

External libraries

Are duplicates detected in external libraries?

Duplicate checking by file hash happens on upload, and only within a library. The same file can therefore appear twice in the timeline, especially with external libraries. Use duplicate review to find look-alikes.

Why can’t I edit details of photos in a read-only library?

In a read-only library (mounted with :ro), Frameleaf can’t write the .xmp sidecar files it uses to store changes, so dates, locations, descriptions and ratings can’t be edited. Read-write libraries (the default) work normally.

What happens when I delete photos from an external library?

When the trash is emptied, Frameleaf deletes the original file from a read-write library. In a read-only library it can’t, so the files reappear in the timeline after the trash is emptied.

Machine learning

Does face recognition use the cloud?

Never. Faces, smart search and text recognition always run on your own server, even with Frameleaf Cloud linked.

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 are a separate, optional feature.

Can I search in languages other than English?

Yes. Choose a multilingual smart search model in Administration, then Settings, then Machine Learning, then Smart Search, then rerun the Smart Search job for all photos. See Search.

Can I use my own CLIP model?

No. Only the models offered in the settings are supported.

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.

Does Frameleaf recognise animals?

Yes, cats and dogs, as 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 the Minimum detection score in the facial recognition settings, for example to 0.8. Going above 0.9 can miss real faces. To stop odd thumbnails being chosen for a person, raise Minimum recognized faces. See People and pets.

How do I turn off machine learning?

Go to Administration, then Settings, then Machine Learning. You can turn it off entirely or by feature, 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 immich-machine-learning service in docker-compose.yml.

Models are corrupt or won’t download

Delete the model cache volume (immich_model-cache with the default project name) so the models download again from scratch. If downloads fail entirely, check the server can reach the Frameleaf model mirror at models.frameleaf.cloud, or the host set in MACHINE_LEARNING_MODEL_SOURCE_URL.

The model cache takes up a lot of space

Old models you no longer use stay in the cache. Mount it and remove the ones you don’t need:

docker run -it --rm -v immich_model-cache:/mnt-models alpine sh
cd /mnt-models
ls clip/ facial-recognition/
# rm -r clip/ABC facial-recognition/DEF   # delete unused models

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, run machine learning on a more powerful computer, or turn machine learning off.

Can I lower CPU and memory use?

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 the concurrency of those jobs to 1. See Jobs.
• In the video transcoding settings, set Threads to 1 or 2.
• In the facial recognition settings, choose the smaller buffalo_s model instead of buffalo_l. It’s faster but less accurate. Rerun face detection for all photos afterwards.
• Choose a lighter model tier for smart search. See Workers and where jobs run.
• Limit the containers’ resources (below), after trying the steps above.

Can I limit CPU and memory use?

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

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.

How can I make machine learning faster?

Raise the concurrency of the Smart Search and Face Detection jobs 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.

The web app says “Server Status Offline” and “Version Unknown”

Your reverse proxy isn’t passing WebSockets. Turn them on; see Reverse proxy.

Docker and the server

How do I see Frameleaf’s logs?

docker logs frameleaf_server
docker logs frameleaf_machine_learning

Add --follow to keep watching new lines. See Troubleshooting.

How do I make Redis less chatty in the logs?

Add this line to the redis service in docker-compose.yml:

    command: redis-server --loglevel warning

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.

The machine learning service says workers are crashing

If the message says a worker is exiting, that’s normal: idle workers shut down to save memory.

• SIGKILL or exit code 137: the container ran out of memory. Add memory, or move machine learning to a computer with more.
• SIGILL or exit code 132: your CPU doesn’t support the instructions the service needs. See Requirements.

How do I wipe Frameleaf and start again?

Danger

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

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

The database folder is on a filesystem that doesn’t support Unix ownership, such as NTFS or exFAT, or on a network share. See Requirements.

How do I check the database for corruption?

See Check the database for corruption.

Should I upgrade Postgres to a newer major version?

Use the Postgres image in the release’s docker-compose.yml. A major Postgres upgrade takes more than changing the image tag. See Database.

Privacy

Can Frameleaf hide sensitive photos?

Yes. Locked 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?

There’s no telemetry. During setup you choose whether to load map tiles and check for updates, and other outside calls Frameleaf doesn’t need stay off. Machine learning models are downloaded from the Frameleaf model mirror. Frameleaf Cloud features only work once you link a server and turn them on. See Environment variables.