Cache and Data Maintenance

Thumbnails and other cached data can be maintained from the dialog accessible by selecting Edit ▸ Cache maintenance .

Each displayed cache location has a Cache data size value, calculated in the background. It is the total size of file contents and symbolic-link entries in that directory tree, rather than allocated disk space. Symbolic links are not followed. Thumbnails stored alongside source images elsewhere are not included.

Select Refresh sizes to recalculate the totals. Sizes also refresh when an in-dialog cleanup, thumbnail rendering, or similarity-cache operation finishes. Use Refresh sizes after an external cache-maintenance job. A directory that does not yet exist is identified separately from a size that could not be calculated. Closing the dialog cancels pending size scans.

Geeqie thumbnail and sim. cache

The utilities listed here operate on the Geeqie caching mechanism. This also includes the data cached for the search and find duplicates utilities.

Clean up: Removes thumbnails, sim. files, and data for which the source image is no longer present, or has been modified since the cached data was generated. Valid similarity grids without perceptual hashes are retained and can be upgraded during similarity-cache creation.
Clear cache: Removes all thumbnails, sim. files, and data stored in the designated folder.

Shared thumbnail cache

The utilities listed here operate on the shared thumbnail mechanism.

Clean up: Removes thumbnails for which the source image is no longer present, or has been modified since the cached data was generated. Valid similarity grids without perceptual hashes are retained and can be upgraded during similarity-cache creation.
Clear cache: Removes all thumbnails stored in the designated folder.

Create thumbnails

This utility will render thumbnails using the current thumbnail caching mechanism, as determined in Preferences .

Render: Pre-render thumbnails for a specific folder, the utility has the following options:
Include subfolders: Enable to include all images contained in the subfolders of folder.
Store thumbnails local to source images: The generated thumbnails will be stored local to the source images, if you have the permissions to write to the folder containing the images.

Create file similarity cache

Some file operations, such as search and find duplicates , are speeded up if similarity data files for the images have been created. This utility will create sim. files recursively under the specified folder. When Perceptual hash algorithm is selected in the Duplicates window, it also creates all eight orientation hashes. Existing RGB grids are reused when adding missing hashes.

The sim. files contain some or all of the following fields:

Dimensions: width x height
DateTimeOriginal: Exif.Photo.DateTimeOriginal in time_t format, or -1 if unavailable. Legacy Date fields are ignored and removed when the cache is rewritten.
checksum: MD5sum 32 character ascii text digest
SimilarityGrid: [32 x 32] = 3072 bytes of data (1024 pixels in RGB format, 1 pixel is 24bits)
PerceptualHashV1: Eight 64-bit DCT perceptual hashes, stored as 16-digit hexadecimal values separated by spaces. These cover all right-angle rotations and reflections. This optional field is added when pHash is enabled; the RGB grid is also retained.

Metadata

This utility operates on the data store for Metadata located in the folder:

$HOME/.local/share/Geeqie/metadata

Clean up

Removes keywords and descriptions for which the source image is no longer present.

Clean and Update Caches

Select Select in the Clean and update caches section, enter or choose a folder, and select Start. Geeqie launches the command line program described below as a separate background job, creating thumbnails and similarity data for the selected folder and all its subfolders. The initial cleanup removes orphaned and outdated entries from Geeqie's cache, not just entries for the selected folder.

Thumbnail caching must be enabled in the saved Preferences. A progress window shows the maintenance stage and current path. Select Stop or close this window to terminate maintenance. The viewer remains available during the background job. The job continues if you close Geeqie; use its progress window to stop it.

Command line program

Geeqie can be run as a command line program: GQ_CACHE_MAINTENANCE=y[es] geeqie --cache-maintenance=<path to images>. It will recursively remove orphaned and outdated thumbnails and .sim files, and create thumbnails and similarity data for all images found.

It may also be called from cron or anacron thus enabling automatic updating of the cached data for all your images.

Scheduling cache maintenance

Run scheduled maintenance as the same user who normally runs Geeqie. Start Geeqie normally at least once and save its configuration before scheduling maintenance. Thumbnail caching must be enabled in Preferences. If you use custom XDG_CONFIG_HOME, XDG_CACHE_HOME, or XDG_DATA_HOME values, set the same values in the maintenance script.

Although maintenance does not open a viewer window, the current GTK4 implementation requires a display connection. For jobs without a desktop session, install Xvfb, xvfb-run (including its xauth dependency), and dbus-run-session using your distribution's package manager. The following wrapper supplies a virtual display and a private D-Bus session.

Save this script as $HOME/.local/bin/geeqie-cache-maintenance, creating the directory if necessary. Replace /usr/bin/geeqie with the absolute path reported by command -v geeqie, and replace the image folder with your own. Check the paths to the wrapper programs too. Quoting the image folder allows spaces in its name.

#!/bin/sh
# SPDX-License-Identifier: GPL-2.0-or-later
export GQ_CACHE_MAINTENANCE=y
exec /usr/bin/xvfb-run --auto-servernum /usr/bin/dbus-run-session -- /usr/bin/geeqie --cache-maintenance="$HOME/Pictures"

Make the script executable, create the log directory, and test it manually before adding a schedule:

chmod +x "$HOME/.local/bin/geeqie-cache-maintenance"
mkdir -p "$HOME/.local/state/geeqie"
"$HOME/.local/bin/geeqie-cache-maintenance" >> "$HOME/.local/state/geeqie/cache-maintenance.log" 2>&1

Check the log for configuration errors or a Caching not enabled message. The examples below append both standard output and errors to this log; remove or rotate it periodically. Ensure the image folder, including any external or network drive, is available when the job runs.

Using cron

Run crontab -e as your normal user and add the following entry to run maintenance daily at 03:00. The cron service must be enabled, and the computer must be running at the scheduled time.

0 3 * * * "$HOME/.local/bin/geeqie-cache-maintenance" >> "$HOME/.local/state/geeqie/cache-maintenance.log" 2>&1

Using anacron

Anacron can run a daily job that was missed while the computer was switched off. To keep maintenance under your own account, create a personal configuration and timestamp directory:

mkdir -p "$HOME/.config" "$HOME/.local/state/geeqie/anacron"

Save the following line in $HOME/.config/geeqie-anacrontab. The first two fields specify a one-day interval and a five-minute delay; the third is the job identifier.

1 5 geeqie-cache-maintenance "$HOME/.local/bin/geeqie-cache-maintenance" >> "$HOME/.local/state/geeqie/cache-maintenance.log" 2>&1

Anacron must itself be started periodically. For example, add this entry with crontab -e to check hourly for a due job. Replace /usr/sbin/anacron with the path reported by command -v anacron. Use this entry instead of the daily cron entry above.

0 * * * * /usr/sbin/anacron -s -t "$HOME/.config/geeqie-anacrontab" -S "$HOME/.local/state/geeqie/anacron" >> "$HOME/.local/state/geeqie/cache-maintenance.log" 2>&1