Immich
FolderSync can sync photos and videos with your own Immich server. Add an account of type Immich.
Experimental
Immich support is new and marked as experimental. Please report any issues to us.
Which Immich versions are supported?
Immich server version 2.0 or newer.
How to login
Immich accounts use an API key instead of your username and password.
- Open the Immich web interface and go to Account Settings → API Keys.
- Select New API Key, give it a name (for example "FolderSync") and copy the key.
- In FolderSync, enter your server address and paste the key into the Secret access key field on the account screen.
- Tap Authenticate account. FolderSync checks the server address and the API key and shows your Immich user name when the login succeeds.
To use a different key, tap Unlink account and authenticate again with the new key.
API key permissions
The easiest option is to give the key all permissions. If you restrict it, the key must be allowed to read your user, read, upload, download and delete assets, and read, create, update and delete albums. Otherwise some sync operations will fail.
What should I enter as server address?
Enter your server's hostname or IP address, or a full URL. Set the port in the port field (Immich's default port is 2283). Examples:
| Server address | Port | Connects to (Desktop) |
|---|---|---|
192.168.1.10 |
2283 | http://192.168.1.10:2283 |
photos.example.com |
443 | https://photos.example.com |
https://photos.example.com |
8443 | https://photos.example.com:8443 |
https://example.com/immich |
443 | https://example.com/immich |
http://nas.local |
2283 | http://nas.local:2283 |
- http or https: if the address starts with
http://orhttps://, that decides whether an encrypted connection is used. Without it, FolderSync uses https on port 443 and http on any other port. Note, only https is allowed on Android. - Port: the port field is always used, unless the address itself contains a port (for example
https://photos.example.com:8443). If Immich is behind a reverse proxy on the standard https port, set the port to 443. - Sub-path: if your reverse proxy serves Immich under a path, include it in the address, for example
https://example.com/immich. You don't need to add/api.
Why can't the Android app connect to my server over http?
FolderSync on Android doesn't allow unencrypted (http) connections, so the Android app always connects with https, even if you enter http://. A default Immich installation only listens on plain http on port 2283, so on Android you need to put Immich behind a reverse proxy with a TLS certificate (for example Caddy, Nginx Proxy Manager or Traefik).
FolderSync Desktop can connect over plain http, for example 192.168.1.10 with port 2283.
If your server uses a self-signed certificate, turn on Allow self-signed certificates, or select your own CA certificate under the advanced settings on the account screen.
How are albums and folders mapped?
Immich has no folders, only a library of photos and albums. In FolderSync:
- the root folder shows your albums as folders, plus all photos and videos that aren't in any album as files
- each album is a folder that contains only files
You can choose the root or a single album as the remote folder for a folder pair. Renaming an album in Immich doesn't break the folder pair, because FolderSync identifies albums by their ID, not their name.
Why are subfolders ignored?
Immich albums can't contain other albums, so FolderSync can only create folders (albums) directly in the root.
- If the folder pair's remote folder is an album, any subfolders in your local folder are ignored.
- If the remote folder is the root, each first-level local subfolder becomes an album, and anything deeper is ignored.
Ignored folders aren't treated as errors. They are listed in the sync log as ignored with the reason "Immich albums cannot contain subfolders". To sync nested folders, create a separate folder pair for each folder, each targeting its own album.
Why are some files ignored?
Immich only stores photos and videos. FolderSync asks your server which file types it supports (for example JPG, HEIC, PNG, RAW formats, MP4 and MOV) and ignores all other files, such as PDFs or documents. Ignored files are shown in the sync log with the reason.
What happens when files are deleted?
When a sync deletes a photo or video on Immich, it's moved to the Immich trash, where you can restore it until Immich empties the trash.
Because Immich stores each photo only once (see below), deleting a photo that is in several albums removes it from all of them.
Deleting an album folder deletes only the album. The photos stay in your Immich library.
Why does the same photo appear in several albums, or keep being uploaded?
Immich detects duplicates by file content and stores each photo only once per user:
- Uploading a photo that already exists in your library doesn't create a copy. The existing photo is added to the target album instead.
- If you have two local files with identical content but different names, Immich keeps only the first name. The second file will then be uploaded again on every sync without creating a duplicate. Remove or exclude one of the copies to avoid this.
Can I rename files?
No. Immich doesn't allow renaming a photo after upload, so file renames aren't supported. Renaming albums (folders) works.
Can I use shared albums?
Yes. Albums other people have shared with you are shown alongside your own. You can sync from them, but changes are limited by your rights in Immich. Deleting or changing photos that belong to someone else, or uploading to an album where you are only a viewer, will fail with an error for those files.
When FolderSync needs to create an album, it never reuses an album owned by someone else. It creates a new album of your own instead.
How are files compared?
Immich provides a SHA1 checksum for every file, which FolderSync uses together with size and modification date. The modification date of the original file is kept when it is uploaded, so unchanged files aren't transferred again.
Files downloaded from Immich are the original files, not previews.
What account information is shown?
After you authenticate, the account screen shows your Immich user name. If your Immich user has a storage quota, it also shows the quota and how much of it is used. Otherwise it shows the size and usage of the Immich server's disk.