Settings
All Lychee settings are stored in the database alongside album and photo metadata. They are accessible to the administrator after logging in by opening the left menu (hamburger icon in the top-left corner), navigating to the Admin page, and clicking the Settings button.
The settings UI organises options into labelled sections. Throughout this reference, settings are annotated with the following tags:
| Tag | Meaning |
|---|---|
| Expert | Hidden by default. Enable the Expert mode toggle at the top of the Settings page to reveal these options. |
| SE | Requires an active Lychee Supporter Edition license. |
| Pro | Requires the Lychee Pro tier. |
Basics
Section titled “Basics”General site-wide options.
dark_mode_enabled
Section titled “dark_mode_enabled”(boolean; default: 1)
Use dark mode for the Lychee UI.
use_admin_dashboard
Section titled “use_admin_dashboard”(boolean; default: 1)
Show an admin dashboard instead of management links in the left menu.
site_owner
Section titled “site_owner”(string; default: John Smith)
Name of the gallery owner, used in the copyright notice and landing page.
site_title
Section titled “site_title”(string; default: Lychee v7)
Browser title for the gallery.
(string; default: en)
Language used by the Lychee interface.
home_page_default
Section titled “home_page_default”(enum: gallery|flow|timeline; default: gallery)
Which page is shown after landing on the root URL.
sm_card_album_source
Section titled “sm_card_album_source”(enum: header|cover; default: header)
Which album photo (header or cover) is used as the Open Graph image when sharing album links on social media.
sm_card_image_url
Section titled “sm_card_image_url”(string; default: empty)
Fallback URL or photo ID for Open Graph images when no album-specific image is available. When empty, the landing page background is used.
is_embed_enabled
Section titled “is_embed_enabled”(boolean; default: 1)
Enable the embed API endpoints and related UI features for embedding Lychee content in external websites. When disabled, all embed endpoints return 404.
new_photos_notification
Section titled “new_photos_notification”(boolean; default: 0) Expert
Send notifications when new photos are uploaded.
Lychee SE
Section titled “Lychee SE”Manage your Supporter Edition license.
disable_se_call_for_actions
Section titled “disable_se_call_for_actions”(boolean; default: 0)
Hide Lychee SE call-for-action prompts throughout the UI. Note that when a valid SE license is active, these prompts are already hidden automatically — this setting is only useful if you want to suppress them without a license.
enable_se_preview
Section titled “enable_se_preview”(boolean; default: 0)
Enable a visual preview of Lychee SE features without an active license.
license_key
Section titled “license_key”(string; default: empty)
Your Lychee SE license key. Obtain one at lycheeorg.dev/get-supporter-edition.
Gallery
Section titled “Gallery”Controls the visual layout and display behaviour of the gallery.
layout
Section titled “layout”(enum: square|justified|masonry|grid; default: justified)
Photo layout inside albums:
- square — All thumbnails are cropped to a uniform square and arranged in a regular grid. Clean and predictable, but crops out parts of each photo.
- justified — Thumbnails preserve their original aspect ratio. Each row is scaled so that photos are flush with both the left and right edges, giving a neat newspaper-like look.
- masonry — Thumbnails preserve their original aspect ratio and are arranged in fixed-width columns, each photo slotting below the shortest column. Rows are not aligned, producing a Pinterest-style layout.
- grid — Similar to square but columns have a configurable minimum width (
photo_layout_grid_column_width). Photos are not cropped; they fill the cell at their natural ratio.
default_album_thumb_aspect_ratio
Section titled “default_album_thumb_aspect_ratio”(enum: 1/1|2/3|3/2|4/5|5/4|16/9; default: 1/1)
Default aspect ratio for album thumbnail covers.
sorting_albums_col
Section titled “sorting_albums_col”(enum: created_at|title|description|max_taken_at|min_taken_at|title_strict|description_strict; default: max_taken_at)
Column used for the default album sort. See the note on title vs title_strict below.
sorting_albums_order
Section titled “sorting_albums_order”(enum: ASC|DESC; default: ASC)
Direction of the default album sort.
sorting_photos_col
Section titled “sorting_photos_col”(enum: created_at|taken_at|title|description|is_highlighted|type|title_strict|description_strict; default: taken_at)
Column used for the default photo sort. See the note on title vs title_strict below.
sorting_photos_order
Section titled “sorting_photos_order”(enum: ASC|DESC; default: ASC)
Direction of the default photo sort.
album_decoration
Section titled “album_decoration”(enum: none|layers|album|photo|all; default: layers)
Decorations displayed on album covers (sub-album count, photo count, or both).
album_decoration_orientation
Section titled “album_decoration_orientation”(enum: column|column-reverse|row|row-reverse; default: row)
Alignment of album decorations: horizontal or vertical.
album_subtitle_type
Section titled “album_subtitle_type”(enum: disabled|description|takedate|creation|oldstyle|num_photos|num_albums|num_photos_albums; default: oldstyle)
What is shown as the subtitle beneath each album in the albums view.
image_overlay_type
Section titled “image_overlay_type”(enum: exif|desc|date|none; default: desc)
Default content shown in the image overlay at the bottom of the photo view.
display_thumb_album_overlay
Section titled “display_thumb_album_overlay”(enum: always|hover|never; default: always)
When to display the title and metadata on album thumbnails.
display_thumb_photo_overlay
Section titled “display_thumb_photo_overlay”(enum: always|hover|never; default: hover)
When to display the title and metadata on photo thumbnails.
thumb_min_max_order
Section titled “thumb_min_max_order”(enum: older_younger|younger_older; default: younger_older)
Which date (older or newer) is displayed first on album thumbnails.
header_min_max_order
Section titled “header_min_max_order”(enum: older_younger|younger_older; default: older_younger)
Which date (older or newer) is displayed first in the album header.
use_album_compact_header
Section titled “use_album_compact_header”(boolean; default: 0)
Disable the large header image inside album views.
autoplay_enabled
Section titled “autoplay_enabled”(boolean; default: 1)
Set the autoplay attribute on video elements.
photos_wraparound
Section titled “photos_wraparound”(boolean; default: 1)
Loop back to the first photo after reaching the last one in an album (and vice versa).
slideshow_timeout
Section titled “slideshow_timeout”(positive integer; default: 5)
Seconds between photos in slideshow mode.
default_license
Section titled “default_license”(license; default: none)
Default Creative Commons license applied to newly uploaded photos.
default_album_protection
Section titled “default_album_protection”(enum: private|public|inherit|public_hidden; default: private)
Default visibility for newly created albums. private = owner only; public = publicly visible; inherit = inherit from parent; public_hidden = public but not listed.
details_links_enabled
Section titled “details_links_enabled”(boolean; default: 0)
Show a module in the photo details panel for easily copying photo URLs.
details_links_public
Section titled “details_links_public”(boolean; default: 0)
Allow anonymous users to use the photo URL copy module.
number_albums_per_row_mobile
Section titled “number_albums_per_row_mobile”(enum: 1|2|3; default: 3) SE
Number of album columns on mobile viewports.
album_layout
Section titled “album_layout”(enum: grid|list; default: grid)
Default album view: grid (thumbnail cards) or list (detailed rows). Users can toggle this client-side, but the preference does not persist across reloads.
albums_per_page
Section titled “albums_per_page”(positive integer; default: 30)
Number of child albums per page in paginated album views.
albums_pagination_ui_mode
Section titled “albums_pagination_ui_mode”(enum: infinite_scroll|load_more_button|page_navigation; default: infinite_scroll)
How album pagination is presented: auto-load on scroll, a manual “Load More” button, or page number navigation.
photos_per_page
Section titled “photos_per_page”(positive integer; default: 100)
Number of photos per page in paginated album views.
photos_pagination_ui_mode
Section titled “photos_pagination_ui_mode”(enum: infinite_scroll|load_more_button|page_navigation; default: infinite_scroll)
How photo pagination is presented: auto-load on scroll, a manual “Load More” button, or page number navigation.
shared_albums_visibility_default
Section titled “shared_albums_visibility_default”(enum: show|separate|separate_shared_only|hide; default: show) Expert
How albums shared by other users appear in the gallery: inline with owned albums, in separate tabs, in tabs (direct shares only), or hidden.
display_exif_data
Section titled “display_exif_data”(boolean; default: 1) Expert
Display EXIF data in the photo details panel. When disabled, EXIF data is not shown anywhere in the UI.
enable_photo_details_always_open
Section titled “enable_photo_details_always_open”(boolean; default: 0) Expert
Keep the photo details drawer open by default when entering the photo view.
photo_layout_gap
Section titled “photo_layout_gap”(positive integer; default: 12) Expert
Gap between columns (in pixels) in Square, Masonry, and Grid photo layouts.
photo_layout_grid_column_width
Section titled “photo_layout_grid_column_width”(positive integer; default: 250) Expert
Minimum column width (in pixels) in the Grid photo layout.
photo_layout_justified_row_height
Section titled “photo_layout_justified_row_height”(positive integer; default: 320) Expert
Row height (in pixels) in the Justified photo layout.
photo_layout_masonry_column_width
Section titled “photo_layout_masonry_column_width”(positive integer; default: 300) Expert
Minimum column width (in pixels) in the Masonry photo layout.
photo_layout_square_column_width
Section titled “photo_layout_square_column_width”(positive integer; default: 200) Expert
Minimum column width (in pixels) in the Square photo layout.
photo_thumb_info
Section titled “photo_thumb_info”(enum: title|description; default: title) Expert
Information shown on photo thumbnails. When description is selected, the date is also hidden.
photo_thumb_tags_enabled
Section titled “photo_thumb_tags_enabled”(boolean; default: 0) Expert SE
Show tags on photo thumbnails in the album view. Has no effect when photo_thumb_info is set to description.
photo_previous_next_size
Section titled “photo_previous_next_size”(enum: small|large; default: small) Expert
Size of the previous/next navigation buttons in the photo view. These buttons are hidden by default and appear only when the cursor approaches the left or right edge of the screen.
slideshow_enabled
Section titled “slideshow_enabled”(boolean; default: 1) Expert
Enable the slideshow functionality.
disable_swipe_effect
Section titled “disable_swipe_effect”(boolean; default: 0)
Disable the swipe animation in the photo viewer.
desktop_dock_full_transparency_enabled
Section titled “desktop_dock_full_transparency_enabled”(boolean; default: 0) Expert
Make the top action bar fully transparent on desktop (visible only on hover).
mobile_dock_full_transparency_enabled
Section titled “mobile_dock_full_transparency_enabled”(boolean; default: 0) Expert
Make the top action bar fully transparent on mobile (visible only on tap). Note: this affects usability on mobile.
albums_infinite_scroll_threshold
Section titled “albums_infinite_scroll_threshold”(positive integer; default: 10) Expert
Number of viewport heights from the bottom of the page at which to trigger loading the next page of albums when using infinite scroll.
photos_infinite_scroll_threshold
Section titled “photos_infinite_scroll_threshold”(positive integer; default: 10) Expert
Number of viewport heights from the bottom of the page at which to trigger loading the next page of photos when using infinite scroll.
low_number_of_shoots_per_day
Section titled “low_number_of_shoots_per_day”(positive integer; default: 10) Expert SE
Shots-per-day threshold considered “low” for punch-card statistics colouring.
medium_number_of_shoots_per_day
Section titled “medium_number_of_shoots_per_day”(positive integer; default: 50) Expert SE
Shots-per-day threshold considered “medium” for punch-card statistics colouring.
high_number_of_shoots_per_day
Section titled “high_number_of_shoots_per_day”(positive integer; default: 100) Expert SE
Shots-per-day threshold considered “high” for punch-card statistics colouring.
Date format settings Expert
Section titled “Date format settings Expert”The following settings accept PHP date format strings:
| Key | Default | Used for |
|---|---|---|
date_format_album_thumb | M Y | Date shown on album thumbnails |
date_format_hero_created_at | M j, Y, g:i:s A T | Album creation date in album details |
date_format_hero_min_max | F Y | Date range in the album hero area |
date_format_photo_overlay | M j, Y, g:i:s A e | Date in the photo overlay |
date_format_photo_thumb | M j, Y, g:i:s A e | Date on photo thumbnails |
date_format_sidebar_taken_at | M j, Y, g:i:s A e | Capture date in the photo sidebar |
date_format_sidebar_uploaded | M j, Y, g:i:s A e | Upload date in the photo sidebar |
Landing Page
Section titled “Landing Page”Controls the optional landing/welcome page shown before entering the gallery.
landing_page_enable
Section titled “landing_page_enable”(boolean; default: 0)
Enable the landing page. When enabled, visitors see a full-screen welcome page before entering the gallery.
landing_title
Section titled “landing_title”(string; default: John Smith)
Title displayed on the landing page.
landing_subtitle
Section titled “landing_subtitle”(string; default: Cats, Dogs & Humans Photography)
Subtitle displayed on the landing page.
landing_background_landscape
Section titled “landing_background_landscape”(string; default: dist/cat.webp)
URL of the background image shown in landscape orientation. Also used as the Open Graph image when sharing the gallery root.
landing_background_landscape_mode
Section titled “landing_background_landscape_mode”(enum: static|photo_id|random|latest_album_cover|random_from_album; default: static)
How the landscape background is sourced: a static URL, a specific photo ID, a random public photo, the latest album cover, or a random photo from a specific album.
landing_background_portrait
Section titled “landing_background_portrait”(string; default: dist/cat.webp)
URL of the background image shown in portrait orientation.
landing_background_portrait_mode
Section titled “landing_background_portrait_mode”(enum: static|photo_id|random|latest_album_cover|random_from_album; default: static)
How the portrait background is sourced (same options as landscape mode).
gallery_header_enabled
Section titled “gallery_header_enabled”(boolean; default: 0)
Show a header image on the main gallery view.
gallery_header_logged_in_enabled
Section titled “gallery_header_logged_in_enabled”(boolean; default: 0)
Show the gallery header image also when a user is logged in.
gallery_header
Section titled “gallery_header”(string; default: empty)
URL of the header image for the gallery view.
gallery_header_bar_transparent
Section titled “gallery_header_bar_transparent”(boolean; default: 1) Expert
Make the gallery header bar transparent so the header image shows through it.
gallery_header_bar_gradient
Section titled “gallery_header_bar_gradient”(boolean; default: 1) Expert
Add a gradient behind the header bar text to improve readability.
site_logo
Section titled “site_logo”(string; default: empty)
URL of a logo image for the gallery header bar. When set, replaces the site title text.
landing_logo
Section titled “landing_logo”(string; default: empty)
URL of a logo image for the landing page intro. When set, replaces the landing title and subtitle text.
landing_header_logo
Section titled “landing_header_logo”(string; default: empty)
URL of a logo image for the top-left corner of the landing page. When set, replaces the landing title and subtitle in that position.
Footer
Section titled “Footer”Controls the content of the page footer.
footer_show_copyright
Section titled “footer_show_copyright”(boolean; default: 1)
Display a copyright message in the footer.
site_copyright_begin
Section titled “site_copyright_begin”(positive integer; default: 2019)
Starting year of the copyright range.
site_copyright_end
Section titled “site_copyright_end”(positive integer; default: 2019)
Ending year of the copyright range.
copyright_text
Section titled “copyright_text”(string; default: empty)
Custom copyright text. When set, replaces the default ”© [year range] [owner]” notice.
footer_additional_text
Section titled “footer_additional_text”(string; default: empty) Expert
Additional HTML text appended below the copyright notice. This field is not sanitized — use with care.
footer_show_social_media
Section titled “footer_show_social_media”(boolean; default: 0)
Show social media icon links in the footer.
Social media URLs
Section titled “Social media URLs”| Key | Documentation |
|---|---|
sm_facebook_url | Facebook profile URL |
sm_flickr_url | Flickr profile URL |
sm_instagram_url | Instagram profile URL |
sm_twitter_url | X (formerly Twitter) profile URL |
sm_youtube_url | YouTube profile URL |
Set any URL to an empty string to hide the corresponding icon.
Smart & Featured Albums
Section titled “Smart & Featured Albums”Configure smart albums and featured (pinned) albums.
enable_unsorted
Section titled “enable_unsorted”(boolean; default: 1)
Enable the Unsorted smart album. Disabling this makes photos without an album invisible.
enable_highlighted
Section titled “enable_highlighted”(boolean; default: 1)
Enable the Starred smart album.
enable_recent
Section titled “enable_recent”(boolean; default: 1)
Enable the Recent uploads smart album.
enable_on_this_day
Section titled “enable_on_this_day”(boolean; default: 1)
Enable the On This Day smart album.
enable_untagged
Section titled “enable_untagged”(boolean; default: 1)
Enable the Untagged smart album (photos with no tags).
recent_age
Section titled “recent_age”(positive integer; default: 1)
Maximum age (in days) of photos shown in the Recent smart album.
enable_smart_album_per_owner
Section titled “enable_smart_album_per_owner”(boolean; default: 0)
When enabled, smart albums show only photos owned by the logged-in user.
SA_override_visibility
Section titled “SA_override_visibility”(boolean; default: 0) Expert
Smart album visibility overrides individual photo visibility, making matching photos publicly accessible regardless of their album settings.
TA_override_visibility
Section titled “TA_override_visibility”(boolean; default: 0) Expert
Tag album visibility overrides individual photo visibility.
PA_override_visibility
Section titled “PA_override_visibility”(boolean; default: 0) Expert
Person album visibility overrides individual photo visibility.
SA_random_thumbs
Section titled “SA_random_thumbs”(boolean; default: 0) Expert
Use random thumbnails for smart albums instead of starred/sorting order.
sorting_pinned_albums_col
Section titled “sorting_pinned_albums_col”(enum: created_at|title|description|max_taken_at|min_taken_at|title_strict|description_strict; default: created_at)
Column used for sorting featured (pinned) albums.
sorting_pinned_albums_order
Section titled “sorting_pinned_albums_order”(enum: ASC|DESC; default: DESC)
Sort direction for featured albums.
deduplicate_pinned_albums
Section titled “deduplicate_pinned_albums”(boolean; default: 0)
Show featured albums only once on the main gallery page (deduplicated).
photos_pagination_limit
Section titled “photos_pagination_limit”(positive integer; default: 500)
Maximum number of photos per page in smart albums.
Star rating smart albums
Section titled “Star rating smart albums”| Key | Default | Description |
|---|---|---|
enable_unrated | 0 | Smart album for photos with no rating |
enable_1_star | 0 | Smart album for photos rated 1.0–1.9 stars |
enable_2_stars | 0 | Smart album for photos rated 2.0–2.9 stars |
enable_3_stars | 0 | Smart album for photos rated 3.0+ stars |
enable_4_stars | 1 | Smart album for photos rated 4.0+ stars |
enable_5_stars | 1 | Smart album for photos with a perfect 5.0 rating |
enable_best_pictures
Section titled “enable_best_pictures”(boolean; default: 1) SE
Enable the Best Pictures smart album (top-rated photos).
best_pictures_count
Section titled “best_pictures_count”(positive integer; default: 100) SE
Number of top-rated photos in the Best Pictures album. Photos tied at the cut-off are all included.
enable_my_rated_pictures
Section titled “enable_my_rated_pictures”(boolean; default: 1)
Enable the My Rated Pictures smart album (all photos rated by the current user).
enable_my_best_pictures
Section titled “enable_my_best_pictures”(boolean; default: 1) SE
Enable the My Best Pictures smart album (top-rated photos by the current user).
my_best_pictures_count
Section titled “my_best_pictures_count”(positive integer; default: 50) SE
Number of top-rated photos in the My Best Pictures album.
Image Processing
Section titled “Image Processing”Controls how photos are processed during upload or import.
thumb_2x
Section titled “thumb_2x”(boolean; default: 1)
Generate HiDPI (2×) square thumbnails.
small_max_height
Section titled “small_max_height”(integer; default: 360)
Maximum height (px) of small thumbnails used in the album view.
small_max_width
Section titled “small_max_width”(integer; default: 0)
Maximum width (px) of small thumbnails. 0 means unconstrained (height only).
small_2x
Section titled “small_2x”(boolean; default: 1)
Generate HiDPI (2×) small thumbnails.
medium_max_height
Section titled “medium_max_height”(integer; default: 1080)
Maximum height (px) of medium images used in the photo view.
medium_max_width
Section titled “medium_max_width”(integer; default: 1920)
Maximum width (px) of medium images.
medium_2x
Section titled “medium_2x”(boolean; default: 1)
Generate HiDPI (2×) medium images.
low_quality_image_placeholder
Section titled “low_quality_image_placeholder”(boolean; default: 1)
Generate low-quality image placeholders (LQIP) for progressive loading.
keep_original_untouched
Section titled “keep_original_untouched”(boolean; default: 1)
Keep the original file unchanged. When auto-rotation is applied, the original is preserved separately.
auto_fix_orientation
Section titled “auto_fix_orientation”(boolean; default: 1)
Automatically rotate images based on EXIF orientation data. Note: enabling this overwrites and recompresses original files (unless keep_original_untouched is also enabled).
compression_quality
Section titled “compression_quality”(positive integer; default: 90)
JPEG compression quality (1–100) used when generating thumbnails and intermediate images.
editor_enabled
Section titled “editor_enabled”(boolean; default: 1)
Allow manual rotation of images via the UI editor.
enable_colour_extractions
Section titled “enable_colour_extractions”(boolean; default: 0) SE
Extract the 5 most dominant colours from each uploaded image (used for colour-based search).
colour_extraction_driver
Section titled “colour_extraction_driver”(enum: league|farzai; default: farzai) Expert SE
Algorithm used for colour extraction. league uses full sampling with CIEDE2000 colour distance (more accurate, slower). farzai uses spot sampling and k-means distance (faster).
upload_chunk_size
Section titled “upload_chunk_size”(integer; default: 0) Expert
Size of upload chunks in bytes. 0 = auto-detect.
upload_processing_limit
Section titled “upload_processing_limit”(integer; default: 4) Expert
Maximum number of images processed in parallel during upload.
raw_download_enabled
Section titled “raw_download_enabled”(boolean; default: 0)
Allow users with download permissions to download the original RAW/HEIC/PSD file preserved during upload.
download_archive_chunked
Section titled “download_archive_chunked”(boolean; default: 0)
Split large album downloads into multiple smaller ZIP files.
download_archive_chunk_size
Section titled “download_archive_chunk_size”(positive integer; default: 300)
Maximum number of photos per ZIP chunk when chunked downloads are enabled.
download_archive_drop_extension_enabled
Section titled “download_archive_drop_extension_enabled”(boolean; default: 1) Expert
Drop file extensions from titles inside ZIP archives, preventing double extensions like image.jpg.jpg.
delete_imported
Section titled “delete_imported”(boolean; default: 0)
Delete original files from the server after Import from Server.
import_via_symlink
Section titled “import_via_symlink”(boolean; default: 0)
Create symbolic links instead of copying files during Import from Server.
skip_duplicates
Section titled “skip_duplicates”(boolean; default: 0)
Skip photos that already exist in the gallery during import (duplicate detection by checksum).
skip_duplicates_early
Section titled “skip_duplicates_early”(boolean; default: 1)
Skip duplicates early during sync imports by checking photo titles in the target album (faster than checksum-based detection).
sync_delete_missing_photos
Section titled “sync_delete_missing_photos”(boolean; default: 0) Expert
Delete photos from Lychee that are no longer present in the synced directory. Only active when sync_dry_run is disabled.
sync_delete_missing_albums
Section titled “sync_delete_missing_albums”(boolean; default: 0) Expert
Delete albums from Lychee that are no longer present in the synced directory. Only active when sync_dry_run is disabled.
sync_dry_run
Section titled “sync_dry_run”(boolean; default: 1) Expert
Run the destructive parts of the sync command in dry-run mode. Disable with care — this allows the sync command to delete albums and photos from your instance.
extract_zip_on_upload
Section titled “extract_zip_on_upload”(boolean; default: 1) SE
Automatically extract ZIP files on upload and import their contents. The ZIP is deleted after successful extraction.
close_upload_on_success
Section titled “close_upload_on_success”(boolean; default: 0)
Auto-close the upload panel when all uploads complete without errors. The panel stays open if any upload fails.
folder_upload_enabled
Section titled “folder_upload_enabled”(boolean; default: 1)
Enable folder drag-and-drop: dragging a folder onto the Albums page creates an album from the folder and uploads its contents. Sub-folders become sub-albums recursively.
folder_upload_max_depth
Section titled “folder_upload_max_depth”(integer; default: 5) Expert
Maximum sub-folder recursion depth for folder uploads. 0 = unlimited; 1 = top-level folder only.
exiftool_path
Section titled “exiftool_path”(string; default: empty) Expert
Path to the exiftool binary. Leave empty to use the system default.
ffmpeg_path
Section titled “ffmpeg_path”(string; default: /usr/bin/ffmpeg) Expert
Path to the ffmpeg binary.
ffprobe_path
Section titled “ffprobe_path”(string; default: /usr/bin/ffprobe) Expert
Path to the ffprobe binary.
has_exiftool
Section titled “has_exiftool”(enum: 0|1|2; default: 1) Expert
Whether exiftool processing is available (0 = no, 1 = yes, 2 = available but disabled).
has_ffmpeg
Section titled “has_ffmpeg”(enum: 0|1|2; default: 1) Expert
Whether ffmpeg processing is available.
imagick
Section titled “imagick”(boolean; default: 1) Expert
Use ImageMagick for image processing when available. Falls back to GD if disabled or unavailable.
local_takestamp_video_formats
Section titled “local_takestamp_video_formats”(string; default: .avi|.mov)
Pipe-separated list of video formats for which the local file modification time is used as the taken-at timestamp (instead of metadata).
lossless_optimization
Section titled “lossless_optimization”(boolean; default: 0) Expert
Apply additional lossless compression to images after thumbnail generation.
prefer_available_xmp_metadata
Section titled “prefer_available_xmp_metadata”(boolean; default: 0) Expert
Use XMP sidecar files for metadata instead of embedded EXIF when both are present.
raw_formats
Section titled “raw_formats”(string; default: .tex)
Pipe-separated list of additional file extensions treated as raw/passthrough files (uploaded but not processed).
use_last_modified_date_when_no_exif_date
Section titled “use_last_modified_date_when_no_exif_date”(boolean; default: 0) Expert
Use the file’s last-modified time as the taken-at date when EXIF data contains no creation date.
Permissions
Section titled “Permissions”Controls public access and download rights.
login_required
Section titled “login_required”(boolean; default: 0)
Require users to log in to access any part of the gallery.
login_required_root_only
Section titled “login_required_root_only”(boolean; default: 1)
Require login only at the root gallery page. Users with a direct link to an album can still access it without logging in.
grants_download
Section titled “grants_download”(boolean; default: 0)
Allow downloading by default (applies to cases not covered by per-album settings, such as photos in private albums shared with individual users).
grants_full_photo_access
Section titled “grants_full_photo_access”(boolean; default: 1)
Allow access to full-resolution photos by default (applies to the same cases as grants_download).
share_button_visible
Section titled “share_button_visible”(boolean; default: 0)
Show a social-sharing button in the gallery header.
unlock_password_photos_with_url_param
Section titled “unlock_password_photos_with_url_param”(boolean; default: 0) Expert
Allow the album password to be passed as a URL query parameter to auto-unlock password-protected albums.
disable_thumb_download
Section titled “disable_thumb_download”(boolean; default: 1) Expert
Prevent downloading of square (200×200) thumbnails.
disable_thumb2x_download
Section titled “disable_thumb2x_download”(boolean; default: 1) Expert
Prevent downloading of HiDPI (400×400) square thumbnails.
disable_small_download
Section titled “disable_small_download”(boolean; default: 0) Expert SE
Prevent downloading of small thumbnails.
disable_small2x_download
Section titled “disable_small2x_download”(boolean; default: 0) Expert SE
Prevent downloading of HiDPI small thumbnails.
disable_medium_download
Section titled “disable_medium_download”(boolean; default: 0) Expert SE
Prevent downloading of medium images.
disable_medium2x_download
Section titled “disable_medium2x_download”(boolean; default: 0) Expert SE
Prevent downloading of HiDPI medium images.
Search
Section titled “Search”search_public
Section titled “search_public”(boolean; default: 0)
Allow anonymous users to use the search bar.
search_minimum_length_required
Section titled “search_minimum_length_required”(positive integer; default: 4)
Minimum number of characters required before a search query is triggered.
search_pagination_limit
Section titled “search_pagination_limit”(positive integer; default: 300)
Maximum number of results shown per search page.
search_photos_layout
Section titled “search_photos_layout”(enum: square|justified|masonry|grid; default: square)
Photo layout used on the search results page.
search_colour_distance
Section titled “search_colour_distance”(integer; default: 30) Expert
Maximum Manhattan RGB distance for palette colour matching: |R−R₀| + |G−G₀| + |B−B₀| ≤ this value.
Timeline
Section titled “Timeline”Controls the timeline view that shows photos and albums grouped by date.
timeline_page_enabled
Section titled “timeline_page_enabled”(boolean; default: 1)
Enable the Timeline page.
timeline_photos_layout
Section titled “timeline_photos_layout”(enum: square|justified|masonry|grid; default: square)
Photo layout on the Timeline page.
timeline_photos_order
Section titled “timeline_photos_order”(enum: taken_at|created_at; default: taken_at)
Whether photos on the Timeline are ordered by capture date or upload date.
timeline_photos_pagination_limit
Section titled “timeline_photos_pagination_limit”(positive integer; default: 200)
Number of photos per page on the Timeline.
timeline_left_border_enabled
Section titled “timeline_left_border_enabled”(boolean; default: 1) SE
Show the vertical left-border line on timelines.
timeline_albums_enabled
Section titled “timeline_albums_enabled”(boolean; default: 1)
Globally enable album timelines within each album. Can also be toggled per album.
timeline_albums_public
Section titled “timeline_albums_public”(boolean; default: 0)
Show the album timeline to anonymous users.
timeline_albums_granularity
Section titled “timeline_albums_granularity”(enum: year|month|day; default: year) SE
Grouping granularity for the album timeline.
timeline_albums_root_enabled
Section titled “timeline_albums_root_enabled”(boolean; default: 1)
Enable the timeline view for albums at the root level.
timeline_photos_enabled
Section titled “timeline_photos_enabled”(boolean; default: 1)
Globally enable photo timelines within each album. Can also be toggled per album.
timeline_photos_public
Section titled “timeline_photos_public”(boolean; default: 0)
Allow anonymous users to access the photo timeline.
timeline_photos_granularity
Section titled “timeline_photos_granularity”(enum: year|month|day|hour; default: day) SE
Grouping granularity for the photo timeline.
Timeline date format settings Expert SE
Section titled “Timeline date format settings Expert SE”Accepts PHP date format strings:
| Key | Default | Used for |
|---|---|---|
timeline_album_date_format_year | Y | Year-level album grouping header |
timeline_album_date_format_month | M Y | Month-level album grouping header |
timeline_album_date_format_day | j M | Day-level album grouping header |
timeline_photo_date_format_year | Y | Year-level photo grouping header |
timeline_photo_date_format_month | M Y | Month-level photo grouping header |
timeline_photo_date_format_day | j M Y | Day-level photo grouping header |
timeline_photo_date_format_hour | g:i | Hour-level photo grouping header |
timeline_quick_access_date_format_year | Y | Year quick-access label on the Timeline page |
timeline_quick_access_date_format_month | M | Month quick-access label |
timeline_quick_access_date_format_day | j M | Day quick-access label |
timeline_quick_access_date_format_hour | h M, g:i | Hour quick-access label |
Configure the photo-frame / slideshow mode accessible via /frame.
mod_frame_enabled
Section titled “mod_frame_enabled”(boolean; default: 1)
Enable the Frame mode. The button is only visible when the access condition is satisfied.
random_album_id
Section titled “random_album_id”(string; default: highlighted)
Album ID used as the source for the Frame. Leave empty to use all searchable photos.
mod_frame_refresh
Section titled “mod_frame_refresh”(integer; default: 30)
Seconds between photo changes in Frame mode.
Map / GPS
Section titled “Map / GPS”Controls map and GPS coordinate features.
map_display
Section titled “map_display”(boolean; default: 0)
Enable map views when photos have GPS coordinates.
map_display_public
Section titled “map_display_public”(boolean; default: 0)
Allow anonymous users to access map views.
map_display_direction
Section titled “map_display_direction”(boolean; default: 1)
Show the camera direction indicator on the map when GPS direction data is available.
map_include_subalbums
Section titled “map_include_subalbums”(boolean; default: 0)
Include photos from sub-albums on the map view.
map_provider
Section titled “map_provider”(map_provider; default: OpenStreetMap.org)
Map tile provider. All providers use OpenStreetMap data. Options include Wikimedia, OpenStreetMap.org, OpenStreetMap.de, OpenStreetMap.fr, and RRZE.
location_decoding
Section titled “location_decoding”(boolean; default: 0)
Decode GPS coordinates into human-readable location names using a reverse-geocoding service.
location_decoding_timeout
Section titled “location_decoding_timeout”(integer; default: 30) Expert
Timeout in seconds for reverse-geocoding queries.
location_show
Section titled “location_show”(boolean; default: 1)
Show the decoded location name in the photo details sidebar (only affects the decoded location, not raw coordinates).
location_show_public
Section titled “location_show_public”(boolean; default: 0)
Show decoded location names to anonymous users.
gps_coordinate_display
Section titled “gps_coordinate_display”(boolean; default: 1)
Display raw latitude/longitude coordinates in the photo details. Disabling this hides GPS coordinates from all users.
gps_coordinate_display_public
Section titled “gps_coordinate_display_public”(boolean; default: 0)
Show GPS coordinates to anonymous users.
rss_enable
Section titled “rss_enable”(boolean; default: 0)
Enable the RSS feed at /rss.
rss_max_items
Section titled “rss_max_items”(positive integer; default: 100)
Maximum number of items in the RSS feed.
rss_recent_days
Section titled “rss_recent_days”(positive integer; default: 7)
Include photos uploaded within the last X days in the RSS feed.
Sensitive Albums
Section titled “Sensitive Albums”Controls how albums marked as sensitive (NSFW) are handled.
nsfw_visible
Section titled “nsfw_visible”(boolean; default: 1)
Show sensitive albums by default (no blurring or hiding).
nsfw_warning
Section titled “nsfw_warning”(boolean; default: 0)
Display a warning the first time a sensitive album is opened.
nsfw_blur
Section titled “nsfw_blur”(boolean; default: 0)
Blur the cover thumbnail of sensitive albums.
nsfw_banner_blur_backdrop
Section titled “nsfw_banner_blur_backdrop”(boolean; default: 0)
Use a blurred backdrop for the sensitive-album warning instead of a solid dark-red overlay.
nsfw_banner_override
Section titled “nsfw_banner_override”(string; default: empty) Expert
Custom HTML warning text for sensitive albums. This field is not sanitized — use with care.
nsfw_warning_admin
Section titled “nsfw_warning_admin”(boolean; default: 0)
Show the sensitive-album warning to logged-in users as well.
flow_blur_nsfw_enabled
Section titled “flow_blur_nsfw_enabled”(boolean; default: 1)
Blur sensitive album photos in the Flow view. Users can un-blur by clicking on the album.
Sensitive content exclusions
Section titled “Sensitive content exclusions”The following settings hide sensitive album content from specific features (all default to 1):
| Key | Description |
|---|---|
hide_nsfw_in_flow | Hide sensitive albums from the Flow view |
hide_nsfw_in_frame | Hide sensitive photos from Frame mode |
hide_nsfw_in_map | Hide sensitive photos from Map views |
hide_nsfw_in_person_albums | Hide sensitive photos from Person Albums |
hide_nsfw_in_rss | Hide sensitive photos from the RSS feed |
hide_nsfw_in_search | Hide sensitive photos from Search results |
hide_nsfw_in_smart_albums | Hide sensitive photos from Smart Albums |
hide_nsfw_in_tag_albums | Hide sensitive photos from Tag Albums |
hide_nsfw_in_tag_listing | Hide sensitive photos from tag photo listings |
hide_nsfw_in_timeline | Hide sensitive photos from the Timeline |
Back Home
Section titled “Back Home”Add a configurable “back” button in the gallery header, useful for embedding Lychee in a larger site.
back_button_enabled
Section titled “back_button_enabled”(boolean; default: 0)
Enable the back/home button in the gallery.
back_button_text
Section titled “back_button_text”(string; default: Return to Home)
Label text for the back button.
back_button_url
Section titled “back_button_url”(string; default: /)
URL the back button links to.
Pro SE
Section titled “Pro SE”Advanced engagement features requiring Lychee SE.
client_side_favourite_enabled
Section titled “client_side_favourite_enabled”(boolean; default: 0) SE
Allow visitors to mark photos as their favourites. Favourites are stored in the browser’s local storage.
metrics_enabled
Section titled “metrics_enabled”(boolean; default: 0) SE
Enable view/share/download statistics on photos and albums. When enabled, anonymous users are counted.
metrics_logged_in_users_enabed
Section titled “metrics_logged_in_users_enabed”(boolean; default: 0) SE
Count logged-in users in statistics (admin users are excluded).
metrics_access
Section titled “metrics_access”(enum: admin|owner|logged-in users|public; default: admin) Expert SE
Who can see album/photo statistics.
live_metrics_enabled
Section titled “live_metrics_enabled”(boolean; default: 0) SE
Enable live metrics providing an activity history of your gallery.
live_metrics_access
Section titled “live_metrics_access”(enum: admin|logged-in users; default: admin) SE
Who can view live metrics.
live_metrics_max_time
Section titled “live_metrics_max_time”(positive integer; default: 30) SE
Maximum retention period for live metrics data, in days.
Privacy Options
Section titled “Privacy Options”Settings to restrict image URL access and protect photo metadata.
temporary_image_link_enabled
Section titled “temporary_image_link_enabled”(boolean; default: 0)
Serve all images via signed (temporary) URLs to prevent hotlinking and unauthorized direct access.
temporary_image_link_when_logged_in
Section titled “temporary_image_link_when_logged_in”(boolean; default: 0)
Use temporary image links for logged-in users as well.
temporary_image_link_when_admin
Section titled “temporary_image_link_when_admin”(boolean; default: 0)
Use temporary image links for admin users as well.
temporary_image_link_life_in_seconds
Section titled “temporary_image_link_life_in_seconds”(positive integer; default: 86400) Expert
Lifetime of temporary image links in seconds (default 24 hours). If you use request caching, set this higher than your cache expiration time.
secure_image_link_enabled
Section titled “secure_image_link_enabled”(boolean; default: 0) Expert SE
Encrypt image links so that the file paths cannot be guessed.
exif_disabled_for_all
Section titled “exif_disabled_for_all”(boolean; default: 0) SE
Disable the details and overlay panels in the front end. Note: this does not remove the data from API responses.
file_name_hidden
Section titled “file_name_hidden”(boolean; default: 0) SE
Hide photo titles from anonymous users. Logged-in users can still see titles.
Flow SE
Section titled “Flow SE”The Flow module displays albums as a social-media-style feed. Only albums containing photos are shown; albums with only child albums are excluded.
flow_enabled
Section titled “flow_enabled”(boolean; default: 1)
Enable the Flow view.
flow_public
Section titled “flow_public”(boolean; default: 0)
Allow anonymous users to access the Flow.
flow_strategy
Section titled “flow_strategy”(enum: auto|opt-in; default: auto) SE
How albums are included in the Flow: auto includes all albums; opt-in includes only albums with Flow explicitly enabled.
flow_base
Section titled “flow_base”(string; default: empty) Expert
Album ID used as the root for the Flow. Leave empty to use the gallery root.
flow_include_sub_albums
Section titled “flow_include_sub_albums”(boolean; default: 0) SE
Include all descendants of the base album, not just direct children.
flow_include_photos_from_children
Section titled “flow_include_photos_from_children”(boolean; default: 0) Expert SE
When an album has no photos but has children, display photos from those children. Not recommended — can cause memory exhaustion and slowdowns.
flow_max_items
Section titled “flow_max_items”(positive integer; default: 10) Expert
Number of albums loaded per Flow page. Lower = more requests; higher = more memory usage.
flow_open_album_on_click
Section titled “flow_open_album_on_click”(boolean; default: 0) SE
Navigate to the album when clicking a Flow card (instead of opening the photo viewer directly).
flow_display_open_album_button
Section titled “flow_display_open_album_button”(boolean; default: 0) SE
Show an “Open Album” button on each Flow card.
flow_image_header_enabled
Section titled “flow_image_header_enabled”(boolean; default: 1) SE
Show an image header at the top of each Flow card featuring the album cover.
flow_image_header_cover
Section titled “flow_image_header_cover”(enum: cover|fit; default: cover) SE
How the header image fills the card header: cover crops to fill; fit scales to fit.
flow_image_header_height
Section titled “flow_image_header_height”(positive integer; default: 24) Expert SE
Height of the image header in rem.
flow_carousel_enabled
Section titled “flow_carousel_enabled”(boolean; default: 1) SE
Show a photo carousel below the image header on each Flow card.
flow_carousel_height
Section titled “flow_carousel_height”(positive integer; default: 6) Expert SE
Height of the photo carousel in rem.
flow_highlight_first_picture
Section titled “flow_highlight_first_picture”(boolean; default: 1) Expert SE
Use the first photo in the album as the main image instead of the album cover.
flow_min_max_enabled
Section titled “flow_min_max_enabled”(boolean; default: 1) SE
Display the min/max date range of the album’s photos on Flow cards.
flow_min_max_order
Section titled “flow_min_max_order”(enum: older_younger|younger_older; default: older_younger) Expert
Which date (older or newer) appears first in the Flow min/max date display.
flow_display_statistics
Section titled “flow_display_statistics”(boolean; default: 1) SE
Show view, share, and download counts on Flow cards.
flow_compact_mode_enabled
Section titled “flow_compact_mode_enabled”(boolean; default: 1) SE
Clamp the description to 3 lines and hide extra information (photo count, child count). A “Show more” button expands the card.
Flow date format settings Expert SE
Section titled “Flow date format settings Expert SE”Accepts PHP date format strings:
| Key | Default | Used for |
|---|---|---|
date_format_flow_published | M j, Y, g:i:s A e | Album published date shown on Flow cards |
date_format_flow_min_max | F Y | Min/max date range on Flow cards |
Watermarker SE
Section titled “Watermarker SE”Automatically apply a watermark image to uploaded photos. Warning: enabling watermarking approximately doubles file-storage usage on your server.
The watermark image is specified by its photo ID (the 24-character identifier visible in the photo’s URL). A PNG with transparent background is recommended.
watermark_enabled
Section titled “watermark_enabled”(boolean; default: 0) SE
Enable watermarking of uploaded photos.
watermark_photo_id
Section titled “watermark_photo_id”(string; default: empty) SE
Photo ID (24-character sequence) of the image to use as the watermark.
watermark_public
Section titled “watermark_public”(boolean; default: 1) SE
Show watermarked versions to anonymous users.
watermark_logged_in_users_enabled
Section titled “watermark_logged_in_users_enabled”(boolean; default: 0) Expert SE
Show watermarked versions to logged-in users.
watermark_original
Section titled “watermark_original”(boolean; default: 0) Expert SE
Also apply the watermark to the original photo (not just intermediate sizes).
watermark_size
Section titled “watermark_size”(positive integer; default: 50) SE
Watermark size as a percentage of the image area (1–100%).
watermark_opacity
Section titled “watermark_opacity”(positive integer; default: 75) SE
Watermark opacity (1–100%). Values below 25 are nearly invisible.
watermark_position
Section titled “watermark_position”(enum: top-left|top|top-right|left|center|right|bottom-left|bottom|bottom-right; default: center) SE
Position of the watermark on the image.
watermark_shift_type
Section titled “watermark_shift_type”(enum: relative|absolute; default: relative) Expert SE
Whether the position shift is relative to image size or in absolute pixels.
watermark_shift_x / watermark_shift_x_direction
Section titled “watermark_shift_x / watermark_shift_x_direction”(integer / enum: left|right; defaults: 0 / right) Expert SE
Horizontal offset and direction of the watermark from its anchor position.
watermark_shift_y / watermark_shift_y_direction
Section titled “watermark_shift_y / watermark_shift_y_direction”(integer / enum: up|down; defaults: 0 / up) Expert SE
Vertical offset and direction of the watermark from its anchor position.
watermark_random_path
Section titled “watermark_random_path”(boolean; default: 1) Expert SE
Store watermarked images at a random path (harder to guess). When disabled, a suffix is appended to the original path.
watermark_optout_disabled
Section titled “watermark_optout_disabled”(boolean; default: 0) SE
Prevent users from opting out of watermarking during upload. All photos will be watermarked according to global settings.
Renamer SE
Section titled “Renamer SE”Automatically rename photos and albums on upload or sync import based on configurable rules.
Note: renaming is likely to interfere with fast duplicate detection for items renamed via sync.
renamer_enabled
Section titled “renamer_enabled”(boolean; default: 0) SE
Enable the renamer module.
renamer_enforced
Section titled “renamer_enforced”(boolean; default: 0) SE
Apply the instance-owner’s renaming rules regardless of individual user settings.
renamer_enforced_before
Section titled “renamer_enforced_before”(boolean; default: 0) SE
Apply owner rules before user rules.
renamer_enforced_after
Section titled “renamer_enforced_after”(boolean; default: 0) SE
Apply owner rules after user rules.
renamer_photo_title_enabled
Section titled “renamer_photo_title_enabled”(boolean; default: 1) SE
Apply renamer rules to photo titles on upload/import.
renamer_album_title_enabled
Section titled “renamer_album_title_enabled”(boolean; default: 1) SE
Apply renamer rules to album titles on creation.
Photo Star Rating
Section titled “Photo Star Rating”Enable users to rate photos on a 1–5 star scale.
rating_enabled
Section titled “rating_enabled”(boolean; default: 1)
Master switch for the photo rating feature.
rating_public
Section titled “rating_public”(boolean; default: 0) SE
Allow all users (including anonymous visitors) to see photo ratings.
rating_show_only_when_user_rated
Section titled “rating_show_only_when_user_rated”(boolean; default: 0) SE
Only display ratings after the current user has submitted their own rating.
rating_show_avg_in_details
Section titled “rating_show_avg_in_details”(boolean; default: 1)
Show the average rating (and rating count) in the photo details sidebar instead of the user’s personal rating.
rating_photo_view_mode
Section titled “rating_photo_view_mode”(enum: always|hover|never; default: hover) SE
When to show the rating overlay in the full photo view.
rating_show_avg_in_photo_view
Section titled “rating_show_avg_in_photo_view”(boolean; default: 0) SE
Show the average rating in the full photo view instead of the user’s personal rating.
rating_album_view_mode
Section titled “rating_album_view_mode”(enum: always|hover|never; default: hover) SE
When to show the rating on photo thumbnails in the album view.
rating_show_avg_in_album_view
Section titled “rating_show_avg_in_album_view”(boolean; default: 1)
Show the average rating on photo thumbnails instead of the user’s personal rating.
Contact SE
Section titled “Contact SE”Manage a contact form that visitors can use to send messages.
contact_form_enabled
Section titled “contact_form_enabled”(boolean; default: 0) SE
Enable the contact form on the website.
contact_form_security_question
Section titled “contact_form_security_question”(string; default: empty) SE
Optional security question shown on the contact form. Leave empty to skip.
contact_form_security_answer
Section titled “contact_form_security_answer”(string; default: empty) SE
Expected answer to the security question (case-insensitive). Ignored when the question is empty.
contact_form_custom_consent_required
Section titled “contact_form_custom_consent_required”(boolean; default: 0) SE
Require users to check a consent checkbox before submitting the contact form (e.g. for GDPR compliance).
AI Vision
Section titled “AI Vision”Integrates with an external AI service for facial recognition, person management, and automatic face scanning.
ai_vision_enabled
Section titled “ai_vision_enabled”(boolean; default: 0)
Master switch for the AI Vision subsystem. When disabled, all AI Vision endpoints and UI elements are inactive.
ai_vision_face_enabled
Section titled “ai_vision_face_enabled”(boolean; default: 0)
Enable facial recognition. Requires ai_vision_enabled = 1. When disabled, face detection endpoints, People pages, and auto-scan on upload are inactive.
ai_vision_face_permission_mode
Section titled “ai_vision_face_permission_mode”(enum: public|private|privacy-preserving|restricted; default: restricted)
Controls who can view person records, face overlays, and manage faces.
ai_vision_face_overlay_enabled
Section titled “ai_vision_face_overlay_enabled”(boolean; default: 1)
Show face bounding-box overlays on photos. When disabled, no face overlays are shown anywhere in the UI.
ai_vision_face_overlay_default_visibility
Section titled “ai_vision_face_overlay_default_visibility”(enum: visible|hidden; default: visible) Expert
Whether face overlays are visible or hidden by default when a photo is opened. Users can toggle with the P key.
ai_vision_face_recognition_warning
Section titled “ai_vision_face_recognition_warning”(boolean; default: 1)
Display a legal warning about facial recognition on the Face Clusters and Face Maintenance pages.
ai_vision_face_selfie_confidence_threshold
Section titled “ai_vision_face_selfie_confidence_threshold”(string/float; default: 0.8) Expert
Minimum confidence score (0.0–1.0) required to automatically link a person via selfie upload.
ai_vision_face_person_is_searchable_default
Section titled “ai_vision_face_person_is_searchable_default”(boolean; default: 1) Expert
Default searchability flag when a new Person record is created.
ai_vision_face_allow_user_claim
Section titled “ai_vision_face_allow_user_claim”(boolean; default: 1) Expert
Allow regular users to claim a Person record to link it to their account. Admins can always claim/unclaim.
ai_vision_nsfw_enabled
Section titled “ai_vision_nsfw_enabled”(boolean; default: 0) SE
Enable automatic NSFW classification of uploaded photos via the external AI service.
ai_vision_nsfw_preset
Section titled “ai_vision_nsfw_preset”(enum: default|strict|moderation|nude_female|permissive|social_media; default: default) SE
Detection preset controlling NSFW classifier sensitivity and which labels trigger each action.
NSFW action settings SE
Section titled “NSFW action settings SE”These settings control what happens when a block-level NSFW finding is detected, per user trust level:
| Key | Options | Default | Applied to |
|---|---|---|---|
ai_vision_nsfw_check_block_action | block|moderate | block | Check-level users |
ai_vision_nsfw_monitor_block_action | block|moderate | moderate | Monitor-level users |
ai_vision_nsfw_trust_but_verify_block_action | block|moderate | moderate | Trust-but-verify users |
ai_vision_nsfw_trust_block_action | block|moderate|approve | approve | Trusted users |
block permanently deletes the photo; moderate holds it for admin review; approve logs the finding but takes no action.
ai_vision_nsfw_sensitive_album_action
Section titled “ai_vision_nsfw_sensitive_album_action”(enum: mark_album|nothing; default: mark_album) SE
Whether a sensitive-tier NSFW finding causes the photo’s album(s) to be marked as sensitive.
ai_vision_nsfw_sensitive_no_album_action
Section titled “ai_vision_nsfw_sensitive_no_album_action”(enum: skip|moderate; default: skip) SE
Fallback when a sensitive finding fires on an unsorted photo with no album. skip logs a warning; moderate holds the photo for review.
ai_vision_nsfw_scan_trusted_users
Section titled “ai_vision_nsfw_scan_trusted_users”(boolean; default: 0) SE
Also scan photos uploaded by Trusted users for NSFW content.
NSFW hide-on-scan settings Expert SE
Section titled “NSFW hide-on-scan settings Expert SE”Temporarily hide photos while the NSFW scan is in progress. If the classifier is unavailable, the photo remains hidden until manually approved.
| Key | Default | Applied to |
|---|---|---|
ai_vision_nsfw_monitor_hide_on_scan | 0 | Monitor-level user uploads |
ai_vision_nsfw_trust_but_verify_hide_on_scan | 0 | Trust-but-verify user uploads |
ai_vision_nsfw_trust_hide_on_scan | 0 | Trusted user uploads |
Gestures
Section titled “Gestures”Configure touch and scroll gesture behaviour for photo navigation.
is_scroll_to_navigate_photos_enabled
Section titled “is_scroll_to_navigate_photos_enabled”(boolean; default: 1)
Navigate between photos by scrolling with the mouse wheel in the photo view.
is_swipe_vertically_to_go_back_enabled
Section titled “is_swipe_vertically_to_go_back_enabled”(boolean; default: 1)
Swipe vertically on a photo to return to the album view.
Users Management
Section titled “Users Management”allow_username_change
Section titled “allow_username_change”(boolean; default: 1)
Allow users to change their own username.
user_registration_enabled
Section titled “user_registration_enabled”(boolean; default: 0)
Allow new users to self-register. When disabled, only admins can create accounts.
default_user_quota
Section titled “default_user_quota”(integer; default: 0) SE
Default storage quota for new users in KB. Set to 0 to disable quota enforcement.
user_invitation_ttl
Section titled “user_invitation_ttl”(positive integer; default: 7) Expert
Maximum lifetime of invitation links in days. Note: invitation links cannot be revoked once issued.
default_user_trust_level
Section titled “default_user_trust_level”(enum: check|monitor|trust_but_verify|trusted; default: trusted)
Default upload trust level assigned to newly created users. check = uploads require admin approval; trusted = uploads are immediately public.
guest_upload_trust_level
Section titled “guest_upload_trust_level”(enum: check|monitor|trust_but_verify|trusted; default: check) SE
Upload trust level for anonymous (guest) uploads.
grant_new_user_modification_rights
Section titled “grant_new_user_modification_rights”(boolean; default: 0)
Allow newly created users to edit their own profile.
grant_new_user_upload_rights
Section titled “grant_new_user_upload_rights”(boolean; default: 0)
Allow newly created users to upload content.
oauth_create_user_on_first_attempt
Section titled “oauth_create_user_on_first_attempt”(boolean; default: 0)
Automatically create a user account on first OAuth login if no matching account exists.
Low-level administrative and maintenance settings.
version
Section titled “version”(integer; default: 070604) Expert
Internal Lychee database schema version. Do not change this.
dropbox_key
Section titled “dropbox_key”(string; default: disabled)
Dropbox API key for the Import from Dropbox feature. Set to disabled to mark the feature as unavailable.
check_for_updates
Section titled “check_for_updates”(boolean; default: 0)
Periodically check GitHub for new Lychee releases and display a notification when one is available.
update_check_every_days
Section titled “update_check_every_days”(positive integer; default: 3)
How often (in days) to check for updates.
allow_online_git_pull
Section titled “allow_online_git_pull”(boolean; default: 1) Expert
Allow updates to be triggered via the web interface using git pull.
apply_composer_update
Section titled “apply_composer_update”(boolean; default: 0) Expert
Run composer update automatically when updating Lychee via the web interface.
hide_version_number
Section titled “hide_version_number”(boolean; default: 0) Expert
Hide the Lychee version number in the login dialog and About screen.
show_keybinding_help_button
Section titled “show_keybinding_help_button”(boolean; default: 1)
Show the keyboard shortcut help button in the gallery header.
show_keybinding_help_popup
Section titled “show_keybinding_help_popup”(boolean; default: 1)
Display the keyboard shortcut help popup automatically on login.
owner_id
Section titled “owner_id”(admin_user; default: 1) Expert
User ID of the installation owner. Changing this allows another admin to take over the server.
(boolean; default: 1) Expert
Use the Zip64 archive format for downloads (supports files >4 GB and >64k entries). Disable only if your users’ unzip tools don’t support Zip64.
zip_deflate_level
Section titled “zip_deflate_level”(enum: -1|0|1|2|3|4|5|6|7|8|9; default: 6) Expert
ZIP compression level. -1 = no compression (STORE method); 0 = DEFLATE with no compression; 1–9 = increasing compression (slower but smaller).
Import via URL security settings Expert
Section titled “Import via URL security settings Expert”These settings guard against Server-Side Request Forgery (SSRF) when using the Import via URL feature. All default to enabled (1) and should only be disabled for specific, trusted environments:
| Key | Default | Description |
|---|---|---|
import_via_url_forbidden_localhost | 1 | Block requests to localhost |
import_via_url_forbidden_local_ip | 1 | Block requests to private/internal IP ranges |
import_via_url_require_https | 1 | Require HTTPS for import URLs |
import_via_url_forbidden_ports | 1 | Restrict to ports 80 and 443 only |
import_via_url_block_redirect | 1 | Do not follow HTTP redirects |
enable_propagate_unlock_option
Section titled “enable_propagate_unlock_option”(boolean; default: 0) Expert
When unlocking a password-protected album, also unlock all other albums that share the same password. Note: this can expose content unintentionally if multiple users share a password.
default_all_settings
Section titled “default_all_settings”(boolean; default: 0)
Show all settings on a single page by default (instead of grouped sections).
default_expert_settings
Section titled “default_expert_settings”(boolean; default: 0)
Enable expert mode in settings by default.
default_old_settings
Section titled “default_old_settings”(boolean; default: 0)
Use the legacy text-input settings view by default.
disable_recursive_permission_check
Section titled “disable_recursive_permission_check”(boolean; default: 1)
Disable the recursive permission check on the Diagnostics page to avoid slowdowns on large libraries.
log_max_num_line
Section titled “log_max_num_line”(positive integer; default: 1000) Expert
Maximum number of log lines displayed on the Logs page.
maintenance_processing_limit
Section titled “maintenance_processing_limit”(positive integer; default: 5000)
Maximum number of operations processed in a single maintenance run. Lower values reduce the risk of timeouts on large libraries.