Offline Mode

Caution

If you are using Docker and want offline assets to persist between container restarts, you will need to mount a volume into the container.

e.g.

volumes:
  - ./offline-assets:/offline-assets  # Mount a local directory to persist cached assets

Caution

Most configuration options cannot be overridden via URL parameters while using Offline Mode. Only a few UI options are allowed:

• use_offline_mode (required for offline mode)
• show_progress
• frameless
• disable_navigation
• clock_source
• refresh
• font_size
• sleep_start
• sleep_end

Offline Mode lets you download assets to the Kiosk server so you don’t need a constant connection to Immich. After downloading, you can view your photos even when Immich is offline. However, an active connection to the Kiosk server is still required to access and display the downloaded assets.

Settings

Key	Value
CONFIG	offline_mode
ENV	N/A
URL	N/A
VALUE	OfflineMode
DEFAULT	""

Using with config.yaml file

offline_mode:
  enabled: true
  number_of_assets: 500
  max_size: 50mb # optional
  expiration_hours: 24 # optional

Use Offline Mode

Enable offline mode for the device/client.

Settings

Key	Value
CONFIG	use_offline_mode
ENV	KIOSK_USE_OFFLINE_MODE
URL	use_offline_mode
VALUE	bool
DEFAULT	false

Using with config.yaml file

use_offline_mode: false

Using with ENV in your docker-compose file

environment:
  KIOSK_USE_OFFLINE_MODE: false

Using with url queries

http://{URL}?use_offline_mode=false

Why it’s useful:

Offline Mode is ideal for setups where maintaining a live connection to Immich might be costly or inefficient. For example, if your Immich storage is hosted on a NAS with disks that spin down to save power, using Offline Mode prevents Kiosk from constantly triggering disk spin-ups.

Limitations of Offline Mode

When using Offline Mode, some Kiosk features are unavailable. These include:

• Experimental Album Video
• Album Ordering
• Like/Hide Buttons

Setting Up Offline Mode

1. Ensure you mount a volume (see note above) if you want offline assets to persist across restarts.

2. Configure Offline Mode by setting the offline_mode.enabled option to true (and any other options you want) in your config.yaml.

3. When accessing Immich Kiosk from a device that needs offline mode, add the use_offline_mode=true parameter to the URL: http://{URL}?use_offline_mode=true

Offline Mode Configuration Options

Value	Default	Description
enabled	false	Enable offline mode
number_of_assets	100	Target number of assets to download
max_size	0	Disk space assets are allowed to take up. You can use mb, gb, tb, etc. 0 = no limit
expiration_hours	0	Number of hours before assets expire. 0 = assets never expire

Example Configuration

Here’s an example configuration for offline mode:

• Downloads up to 500 assets
• Limits total disk usage to 50MB
• Deletes downloaded assets after 24 hours if Kiosk is able to reach your Immich server

offline_mode:
  enabled: true
  number_of_assets: 500
  max_size: 50mb # optional
  expiration_hours: 24 # optional