Skip to main content

📱 LibrePhotos Mobile

LibrePhotos Mobile is the official app. It stores a local copy of your library on the device, so you can browse your photos, albums, and people with no connection at all — the network is used only to catch the app up with the server and to back up new photos from your phone.

It runs on Android and iOS.

Not released yet

LibrePhotos Mobile has not been published anywhere yet: there is no build on the Google Play Store, the App Store, F-Droid, or TestFlight, and no .apk of it on the GitHub releases page. Until it is, the only way to use it is to run it from the source code, as described below. If you want an app you can install from a store today, see UhuruPhotos.

Trying the app​

The app lives in apps/mobile/ of the LibrePhotos repository. To run it you need a computer with Node.js 24 and a checkout of the repository:

git clone https://github.com/LibrePhotos/librephotos.git
cd librephotos
npm ci            # installs the app and the shared API client
cd apps/mobile

Then pick one of two ways to get it onto your phone:

  • Expo Go (quickest). Install the free Expo Go app on your phone, run npx expo start --go on the computer, and scan the QR code it prints. The phone has to reach the computer over the network, and Expo Go loads the app from it, so keep expo start running while you use the app. This works on Android and on iPhone.
  • Development build (closer to a real install). On Android, with Android Studio and a phone connected over USB (or an emulator), run npx expo run:android. It builds the app and installs it on the device as LibrePhotos. Background backup and the share target behave best in a development build. On iOS a development build needs a Mac with Xcode and a paid Apple Developer account.

The developer guide and the app README cover the setup in more detail. Problems and feedback are welcome on the issue tracker with the mobile label.

First login​

When you first open the app you are asked for your server address before anything else — this is a self-hosted app, so it needs to know where your LibrePhotos lives.

  1. In the Server field, enter the same address you use to reach LibrePhotos in a browser, for example photos.example.com or 192.168.1.10:3000. The protocol is optional.
  2. Wait for the connection check to succeed.
  3. Sign in with your LibrePhotos username and password.

Your login is stored securely on the device. After the first sign-in the app begins downloading a copy of your library in the background (see Offline mode).

Offline mode​

After the first sync, the app keeps a local mirror of your library — photos, albums, people, and shared items — together with grid thumbnails. That means you can open the app in airplane mode and still:

  • browse the full timeline and scroll through every photo's thumbnail,
  • open albums, people, places, things, and tags,
  • favorite, hide, trash/restore, rate, caption, and add or remove photos from albums.

Changes you make offline are saved immediately and queued. The next time the app is online it sends them to the server automatically. A star rating is written to the photo's file or XMP sidecar when Write edits to files is on, the same as a favorite set on the web.

Star ratings New in 1.3.0

Until this fix, a star rating set in the app showed on the phone but never reached the server. Saving ratings needs a build of the app that includes the fix and a server newer than 1.2.1 (1.3.0 or later); an older server rejects the rating and the app shows an error. Ratings set before the fix exist only on that phone, so set them again once both are updated.

Full-resolution originals are fetched on demand when you open a photo, so viewing an original still needs a connection unless it is a photo already on your device.

Backup setup​

The app can back up new photos and videos from your phone's camera roll to your LibrePhotos server.

  1. Open the Backup tab.
  2. Grant photo-library access when prompted. On iOS you can grant access to all photos or a limited selection — the app backs up whatever it is allowed to see.
  3. Choose which albums to back up (for example only your Camera roll).
  4. Set the conditions: back up on Wi-Fi only and/or only while charging.

Backup needs two things an admin sets up on the server:

  • Uploads must be enabled. The Allow uploads switch in the admin area has to be on. That switch is the authoritative setting; the ALLOW_UPLOAD environment variable only supplies its initial default (see Environment variables).
  • Your account needs a Scan Directory that exists on the server. Uploaded files are saved in its uploads/web/ folder, or in the web/ folder inside the upload folder an admin set for you (see Upload folder). See How to Change Your Scan Directory.

If either is missing, the server rejects the upload.

The Backup tab shows progress and a per-item queue. Photos already on the server (matched by content, so duplicates are never re-uploaded) are skipped. A backed- up photo's badge flips from pending to synced once the server confirms it. Backup continues in the background within the limits your phone's operating system allows; keeping the app in the foreground is the fastest way to clear a large backlog.

Sync status and repair​

Open Sync status (from Settings) to see what the app is doing:

  • the last sync time and result,
  • how many items were added, updated, or removed,
  • a running log you can export to attach to a bug report.

Because the local copy is disposable, the app can always recover from a bad state by re-syncing from scratch. If counts ever drift from the server the app schedules this automatically, and you can trigger it yourself from the Sync status screen. A re-sync never loses server data — it just rebuilds the local mirror.

Memories reminder​

The app can remind you about your memories — photos from this day in previous years. Enable the reminder in Settings to get a local notification; tapping it opens that day's memories. The reminder uses a local notification scheduled on the device, so it works without any push service.

Share target​

LibrePhotos Mobile registers as a share target. From another app — Photos, a browser, a messaging app — use the system Share sheet and pick LibrePhotos to send images into your library. On Android this works in a development build (not in Expo Go, which registers as its own app); on iOS the share extension is being finalized.