Skip to main content

Offline Usage

To enable LibrePhotos to run its machine learning features offline, you can manually download and place the required models by following the steps outlined below. This guide assumes that you have access to the Internet initially to download the models and then configure LibrePhotos to run in an offline environment.

Step 1: Download the Models Manually​

Manually download the necessary models from their respective URLs. Below is a list of models used by LibrePhotos, along with their download links. OpenCLIP is always needed. Not released yet: the captioning and face recognition models are optional; skip the ones whose feature you turned off (see Running with minimal machine learning), and LibrePhotos does not ask for them either.

  1. openclip_vitb32 (Tags, semantic search and similar photos; always required)
    • https://huggingface.co/derneuere/librephotos_models/resolve/main/openclip_vitb32/visual.onnx
    • https://huggingface.co/derneuere/librephotos_models/resolve/main/openclip_vitb32/textual.onnx
    • https://huggingface.co/derneuere/librephotos_models/resolve/main/openclip_vitb32/tokenizer.json
    • https://huggingface.co/derneuere/librephotos_models/resolve/main/openclip_vitb32/preprocess.json
    • https://huggingface.co/derneuere/librephotos_models/resolve/main/openclip_vitb32/LICENSE
  2. lfm2_vl_450m (Captioning; optional, not needed with FEATURE_IMAGE_CAPTIONING=false or Captioning Model None)
    • https://huggingface.co/onnx-community/LFM2.5-VL-450M-ONNX/resolve/main/onnx/vision_encoder_q4.onnx
    • https://huggingface.co/onnx-community/LFM2.5-VL-450M-ONNX/resolve/main/onnx/vision_encoder_q4.onnx_data
    • https://huggingface.co/onnx-community/LFM2.5-VL-450M-ONNX/resolve/main/onnx/embed_tokens_q4.onnx
    • https://huggingface.co/onnx-community/LFM2.5-VL-450M-ONNX/resolve/main/onnx/embed_tokens_q4.onnx_data
    • https://huggingface.co/onnx-community/LFM2.5-VL-450M-ONNX/resolve/main/onnx/decoder_model_merged_q4.onnx
    • https://huggingface.co/onnx-community/LFM2.5-VL-450M-ONNX/resolve/main/onnx/decoder_model_merged_q4.onnx_data
    • Tokenizer: https://huggingface.co/onnx-community/LFM2.5-VL-450M-ONNX/resolve/main/tokenizer.json
  3. buffalo_sc (Face recognition — default model; optional, not needed with FEATURE_FACE_DETECTION=false)
    • URL: https://github.com/deepinsight/insightface/releases/download/v0.7/buffalo_sc.zip
    • Only download the model selected in Site Settings → Face Recognition Model. The other options use the same release, e.g. buffalo_s.zip, buffalo_m.zip, buffalo_l.zip, antelopev2.zip.

Step 2: Place the Models in the Correct Location​

Once the models are downloaded, place them in the following directory:

<LibrePhotos Media Root Directory>/data_models/

MEDIA_ROOT is not something you set directly — it is derived from BASE_DATA (default /), so inside the container it is always /protected_media. On the host it is whichever directory you mounted to /protected_media. With the standard docker-compose install that is ${data}/protected_media, which defaults to ./librephotos/data/protected_media/, so the models go in ./librephotos/data/protected_media/data_models/.

  • openclip_vitb32 files -> Place all five in <MEDIA_ROOT>/data_models/openclip_vitb32/ under their own names
  • lfm2_vl_450m files -> Place all seven in <MEDIA_ROOT>/data_models/lfm2_vl_450m/ under their own names. The .onnx_data files hold the weights the small .onnx graphs point at, so the names must not change.
  • buffalo_sc.zip -> Unpack into <MEDIA_ROOT>/data_models/face_recognition/models/buffalo_sc/ (the folder should contain the .onnx files)

Step 3: Verify Model Placement​

Ensure that all models are correctly placed and unpacked in their respective directories. The structure should look something like this:

data_models/
    ├── openclip_vitb32/
    │   ├── visual.onnx
    │   ├── textual.onnx
    │   ├── tokenizer.json
    │   ├── preprocess.json
    │   └── LICENSE
    ├── lfm2_vl_450m/
    │   ├── vision_encoder_q4.onnx
    │   ├── vision_encoder_q4.onnx_data
    │   ├── embed_tokens_q4.onnx
    │   ├── embed_tokens_q4.onnx_data
    │   ├── decoder_model_merged_q4.onnx
    │   ├── decoder_model_merged_q4.onnx_data
    │   └── tokenizer.json
    └── face_recognition/
        └── models/
            └── buffalo_sc/

Step 4: Turn Off the Online Map Services​

Even with every model stored locally, two settings still reach the Internet by default:

  • Site Settings → Map Tiles defaults to PhotoPrism (default), which loads the map background from https://cdn.photoprism.app/maps/default.json every time a map is shown. The OpenStreetMap option is not an offline alternative either — it fetches tiles from tile.openstreetmap.org and fonts from fonts.openmaptiles.org. On an offline install, select None (hide map), which turns off map rendering and makes no external requests.
  • Site Settings → Map Provider (reverse geocoding) is ExifTool (offline, built in) on a new install: it looks place names up in a database that ships with LibrePhotos and needs no Internet access. It names towns, not streets; see Offline place names with ExifTool. An install set up before 1.4.0 keeps the provider it had, usually Nominatim (OpenStreetMap), which calls the public Nominatim service during scans; without Internet access these calls fail and are only logged as a warning, so photos keep their coordinates but get no place names. Select ExifTool there, then Look up place names again under Admin Area → Admin Tools (see Switching the provider). The place search in the location picker still needs Nominatim, so it does not work offline; clicking the map and pasting coordinates do. Not released yet (comes after 1.3.0) Up to 1.3.0 there was no offline provider, so place names were unavailable offline.

Step 5: Run LibrePhotos​

You can now run LibrePhotos without an active Internet connection for the machine learning features. The application will use the models you manually downloaded and placed in the data_models directory.