latest version: 2.9.1
© 2011-2022 Lukas Spies

Please consider donating to support humanitarian relief efforts in Ukraine.

Online Manual

Here you can find an overview of all the settings, a short explanation what it controls, and their values in the settings database with the corresponding database table shown ahead of the setting key. The default value is usually shown in bold. The settings database is located in the CONFIG_DIR which on Linux systems typically is ~/.config/PhotoQt/. The settings are grouped in the same way as they are in the settings manager, which typically also corresponds to the equivalent table in the settings database.

Settings marked with an asterisk* are hidden unless the expert mode is enabled. The expert mode can be enabled using the "advanced" button at the bottom left of the settings manager.

Explore settings for tab: Interface | Image View | Thumbnails | Metadata

languageHere the language of PhotoQt can be chosen. The available choices are all largely if not fully completed. If you want to help with the translations, you can request a new language or to join a team over at CrowdIn.

On first start PhotoQt tries to detect your system language and, if a translation for that language is available, sets that language as default.

// Entry in CONFIG_DIR/settings.db:
  • interface / Language
status informationThe status information shows some basic data about the current folder and photo in the top left corner of the window. The items can be reordered using drag-and-drop.

// Entry in CONFIG_DIR/settings.db:
  • interface / StatusInfoShow={0,1}
  • interface / StatusInfoList=counter:://::filename:://::zoom:://::rotation
  • interface / StatusInfoFontSize={6-10-30}
  • interface / StatusInfoManageWindow={0,1}
window modePhotoQt can be used just as well in both fullscreen mode and as a normal window.

// Entry in CONFIG_DIR/settings.db:
  • interface / WindowMode={0,1}
  • interface / WindowDecoration={0,1}
window buttonsPhotoQt can show some integrated window buttons at the top right corner of the screen.

// Entry in CONFIG_DIR/settings.db:
  • interface / WindowButtonsShow={0,1}
  • interface / WindowButtonsSize={5-10-25}
  • interface / WindowButtonsAlwaysShowX={0,1}
navigation buttonsSome buttons to help with navigation. These can come in handy when, e.g., operating with a touch screen.

They can be shown in its own floating window and/or to the left of the window buttons in the top right corner of the screen.

// Entry in CONFIG_DIR/settings.db:
  • interface / NavigationFloating={0,1}
  • interface / NavigationTopRight={0,1}
tray iconPhotoQt can display a tray icon in the system tray. It can either be shown only during each session, or PhotoQt can hide to the system tray when closed. It is also possible to start PhotoQt already minimised to the tray (e.g. at system startup) when called with "--start-in-tray".

// Entry in CONFIG_DIR/settings.db:
  • interface / TrayIcon={0,1,2}
backgroundThe background of PhotoQt is the part, that is not covered by an image. It can either be really (half-)transparent, faked transparent (instead of the actual desktop a screenshot of it is shown), or a custom background image can be set.

Note: Fake transparency only really works when PhotoQt is run in fullscreen/maximised.

// Entry in CONFIG_DIR/settings.db:
  • interface / BackgroundImageScreenshot={0,1}
  • interface / BackgroundImageUse={0,1}
  • interface / BackgroundImagePath=""
  • interface / BackgroundImageScale={0,1}
  • interface / BackgroundImageScaleCrop={0,1}
  • interface / BackgroundImageStretch={0,1}
  • interface / BackgroundImageCenter={0,1}
  • interface / BackgroundImageTile={0,1}
overlay color*This is the color that is shown on top of the transparency or custom background image. If no compositor is available or the alpha value is set to 255, then the background will be a single solid color. It is also possible to specify distinct color for when PhotoQt is run in window mode and when it is run in fullscreen

// Entry in CONFIG_DIR/settings.db:
  • interface / OverlayColorAlpha={0-190-255}
  • interface / OverlayColorBlue={0-255}
  • interface / OverlayColorGreen={0-255}
  • interface / OverlayColorRed={0-255}
  • interface / FullscreenOverlayColorDifferent={0,1}
  • interface / FullscreenOverlayColorAlpha={0-190-255}
  • interface / FullscreenOverlayColorBlue={0-255}
  • interface / FullscreenOverlayColorGreen={0-255}
  • interface / FullscreenOverlayColorRed={0-255}
pop out elementsMany of the elements (e.g., the main menu, the file dialog, the settings manager, etc.) are mostly by default shown integrated into the main window. Depending on your workflow or usage of PhotoQt, it can be advantageous to show some or all of the elements in their own window, separate from the main interface.

// Entry in CONFIG_DIR/settings.db:
  • interface / PopoutAbout={0,1}
  • interface / PopoutAdvancedSort={0,1}
  • interface / PopoutChromecast={0,1}
  • interface / PopoutFileDelete={0,1}
  • interface / PopoutFileRename={0,1}
  • interface / PopoutFileSaveAs={0,1}
  • interface / PopoutFilter={0,1}
  • interface / PopoutHistogram={0,1}
  • interface / PopoutImgur={0,1}
  • interface / PopoutMainMenu={0,1}
  • interface / PopoutMetadata={0,1}
  • interface / PopoutOpenFile={0,1}
  • interface / PopoutOpenFileKeepOpen={0,1}
  • interface / PopoutScale={0,1}
  • interface / PopoutSettingsManager={0,1}
  • interface / PopoutSlideShowControls={0,1}
  • interface / PopoutSlideShowSettings={0,1}
  • interface / PopoutWallpaper={0,1}
popout when needed*Some elements require a minimum amount of space. When the window is smaller than that, those elements can be automatically popped out to provide the space they need.

// Entry in CONFIG_DIR/settings.db:
  • interface / PopoutWhenWindowIsSmall={0,1}
remember last imageAt startup, you can set PhotoQt to re-open the last used image and directory. This doesn't keep any zooming/scaling/mirroring from before. An image passed on through the command line always takes precedence over this setting.

// Entry in CONFIG_DIR/settings.db:
  • interface / StartupLoadLastLoadedImage={0,1}
empty area around imageThis settings governs what happens when a click occurs outside of the actual visible image (i.e., on the empty background). It can be set to either close the application, toggle the window decoration on/off, and navigate backwards/forwards in the folder when the click occurs on the background in the right/left half of the window.

Note that if you use a mouse click for a shortcut already, then this option wont have any effect!

// Entry in CONFIG_DIR/settings.db:
  • interface / CloseOnEmptyBackground={0,1}
  • interface / NavigateOnEmptyBackground={0,1}
  • interface / WindowDecorationOnEmptyBackground={0,1}
size of 'Hot Edge'*Here you can adjust the sensitivity of the metadata and main menu elements. The main menu opens when your mouse cursor gets close to the right screen edge, the metadata element when you go to the left screen edge (if enabled). This setting controls how close to the screen edge you have to get before they are shown.

// Entry in CONFIG_DIR/settings.db:
  • interface / HotEdgeSize={1-4-20}
window management*There are some simple window management functions available from inside PhotoQt:

1. The window itself can be moved an maximized through the labels (not available on Wayland).
2. The window geometry can be preserved between sessions (not available on Wayland).
3. The window can be kept above other windows.

// Entry in CONFIG_DIR/settings.db:
  • interface / StatusInfoManageWindow={0,1}
  • interface / SaveWindowGeometry={0,1}
  • interface / KeepWindowOnTop={0,1}
mouse wheel sensitivity*The mouse can be used for various things, including many types of shortcuts. The sensitivity of the mouse wheel defines the distance the wheel has to be moved before triggering a shortcut.

// Entry in CONFIG_DIR/settings.db:
  • interface / MouseWheelSensitivity={1-10}
custom context menu entriesIt is possible to add custom entries to the context menu that is (by default) shown on right click on the background. It is also possible to add those entries to the main menu (expert mode).

The following placeholders can be used:
  • %f = filename including path
  • %u = filename without path
  • %d = path without filename

// Entry in CONFIG_DIR/settings.db:
  • mainmenu / ShowExternal={0,1}

Image View
sort images byImages in the current folder can be sorted in various ways. They can be sorted by filename, natural name (e.g., file10.jpg comes after file9.jpg and not after file1.jpg), filesize, date, and their type (based on mime type), all of that both ascending or descending.

// Entry in CONFIG_DIR/settings.db:
  • imageview / SortImagesBy={name, naturalname, time, size, type}
  • imageview / SortImagesAscending={0,1}
transparency markerTransparency in an image is, by default, shown as normal transparency in the displayed image. It is also possible to optionally show the typical pattern of dark/light squares (like a checkerboard).

// Entry in CONFIG_DIR/settings.db:
  • imageview / TransparencyMarker={0,1}
fit in windowIf the image dimensions are smaller than the screen dimensions, PhotoQt can automatically zoom those images to make them fit into the window.

// Entry in CONFIG_DIR/settings.db:
  • imageview / FitInWindow={0,1}
loopingPhotoQt can loop over the images in the folder, i.e., when reaching the last image it continues to the first one and vice versa. If disabled, it will stop at the first/last image.

// Entry in CONFIG_DIR/settings.db:
  • / LoopThroughFolder={0,1}
margin*A loaded image is shown across the full window size, from edge to edge. It is possible to add a margin of a few pixels around the image.

// Entry in CONFIG_DIR/settings.db:
  • imageview / Margin={0-5-100}
pixmap cache*Fully loaded image can be cached, so that, when they are loaded again, they are shown nearly instantaneously. This does, however, increase the memory usage. Here the maximum memory to be used by this cache can be chosen. Once the cache reaches its memory limit, the oldest entries in the cache will be purged to make room for the new one.

// Entry in CONFIG_DIR/settings.db:
  • imageview / Cache={15-512-4096}
animationTransitioning from one image to another can be done using one of a few different animations:
  • opacity: fade one image into another
  • along x-axis: move image along the x-axis in/out of the screen
  • along y-axis: move image along the y-axis in/out of the screen
  • rotation: rotate one image into the next
  • explosion: explode image out of screen
  • implosion: implode image in of screen
  • random: choose one of the above at random every time
In addition to the type of animation, its speed can also be adjusted here.

// Entry in CONFIG_DIR/settings.db:
  • imageview / AnimationType={opacity, x, y, rotation, explosion, implosion, random}
  • imageview / AnimationDuration={0-3-10}
interpolation*There are many different interpolation algorithms out there. Depending on the choice of interpolation algorithm, the image (when zoomed in) will look slightly differently. PhotoQt uses mipmaps to get the best quality for images. However, for very small images, that might lead to too much blurring causing them to look rather ugly. For those images, the 'Nearest Neighbour' algorithm tends to be a better choice. The threshold defines for which images to use which algorithm.

// Entry in CONFIG_DIR/settings.db:
  • / InterpolationDisableForSmallImages={0,1}
  • / InterpolationThreshold={0-100-1000}
remember per session*Applying zoom/rotation/flip/position to an image is typically not stored anywhere. If you load the same image again, it will be shown reset to the defaults. With this option, the zoom/rotation/flip/position of an image is remembered per session.

Note that these three properties are never kept between sessions. Closing PhotoQt will always reset those properties.

// Entry in CONFIG_DIR/settings.db:
  • / RememberZoomRotationMirror={0,1}
zoom to/fromThis controls whether the image is zoomed to/from the mouse position or to/from the image center. Note that this only applies when zooming by mouse, zooming by keyboard shortcut always zooms to/from the image center.

// Entry in CONFIG_DIR/settings.db:
  • imageview / ZoomToCenter={0,1}
zoom speed*Zooming an image in/out is done smoothly at a certain speed. How fast/slow this should happen can be adjusted here.

// Entry in CONFIG_DIR/settings.db:
  • / ZoomSpeed={1-20-100}
zoom min/max*This defines the minimum and/or maximum zoom level for an image.

Note that the maximum zoom level is the absolute zoom level, the minimum zoom level is relative to the default zoom level (the zoom level when the image is first loaded).

// Entry in CONFIG_DIR/settings.db:
  • imageview / ZoomMinEnabled={0,1}
  • imageview / ZoomMin={1-20-100}
  • imageview / ZoomMaxEnabled={0,1}
  • imageview / ZoomMax={100-500-1000}

SizeHere you can adjust the thumbnail size. You can set it to any size between 20 and 256 pixel. Per default it is set to 80 pixel, but the optimal size depends on the screen resolution.

// Entry in CONFIG_DIR/settings.db:
  • / ThumbnailSize={20-80-256}
SpacingThe thumbnails are shown in a row at the lower or upper edge. The spacing in between each thumbnail (if any) can be adjusted here.

// Entry in CONFIG_DIR/settings.db:
  • / ThumbnailSpacingBetween={0-50}
Lift UpWhen the cursor is above a thumbnail, or if the thumbnail corresponds to the currently shown main image, it jumps up a few pixels, however many are set with this option.

// Entry in CONFIG_DIR/settings.db:
  • / ThumbnailLiftUp={0-6-100}
VisibilityThe thumbnails normally fade out when not needed, however, they can be set to stay visible. The main image is shrunk to fit into the free space. When it is zoomed in the thumbnails can be set to fade out automatically.

// Entry in CONFIG_DIR/settings.db:
  • / ThumbnailKeepVisible={0,1}
  • / ThumbnailKeepVisibleWhenNotZoomedIn={0,1}
Keep in CenterWith this option the current thumbnail (i.e., the thumbnail of the currently displayed image) will always be kept in the center of the thumbnail bar (if possible). If this option is not set, then the active thumbnail will simply be kept visible, but not necessarily in the center.

// Entry in CONFIG_DIR/settings.db:
  • / ThumbnailCenterActive={0,1}
PositionThe thumbnails can be shown either along the lower or upper edge of the window.

// Entry in CONFIG_DIR/settings.db:
  • / ThumbnailPosition={Top,Bottom}
Filename LabelOn each thumbnail a label with the filename can be written at whatever font size chosen with this option.

// Entry in CONFIG_DIR/settings.db:
  • / ThumbnailWriteFilename={0,1}
  • / ThumbnailFontSize={5-7-20}
Filename Only*Instead of thumbnails a placeholder containing nothing but the filename with a large font can be shown. For slower computers, this can speed up loading a directory while still providing some help navigating through the images.

// Entry in CONFIG_DIR/settings.db:
  • / ThumbnailFilenameInstead={0,1}
  • / ThumbnailFilenameInsteadFontSize={5-10-40}
Disable thumbnailsIf no thumbnails are needed/wanted, they can be completely disabled here. This will increase the speed of PhotoQt, but might make navigating the images a little harder.

// Entry in CONFIG_DIR/settings.db:
  • / ThumbnailDisable={0,1}
Thumbnail Cache*Thumbnails can be cached to improve the speed of loading the thumbnails in subsequent sessions. The caching is done according to the freedesktop.org standard and thus different applications can share the same thumbnail for the same image file.

// Entry in CONFIG_DIR/settings.db:
  • / ThumbnailCache={0,1}
Threads*Multiple thumbnails can be created in parallel in order to greatly improve the speed of loading thumbnails. The number of threads should ideally be lower than the number of cores available to avoid blocking the machine for other processes.

// Entry in CONFIG_DIR/settings.db:
  • / ThumbnailMaxNumberThreads={1-4-8}

Meta InformationPhotoQt can display a variety of meta information about the current image in the meta data element (hidden along the left edge of the screen). Most of the data is extracted using the external library Exiv2.

// Entry in CONFIG_DIR/settings.db:
  • / MetaFilename={0,1}
  • / MetaFileType={0,1}
  • / MetaFileSize={0,1}
  • / MetaImageNumber={0,1}
  • / MetaDimensions={0,1}
  • / MetaCopyright={0,1}
  • / MetaExposureTime={0,1}
  • / MetaFlash={0,1}
  • / MetaFLength={0,1}
  • / MetaFNumber={0,1}
  • / MetaGps={0,1}
  • / MetaIso={0,1}
  • / MetaKeywords={0,1}
  • / MetaLightSource={0,1}
  • / MetaLocation={0,1}
  • / MetaMake={0,1}
  • / MetaModel={0,1}
  • / MetaSceneType={0,1}
  • / MetaSoftware={0,1}
  • / MetaTimePhotoTaken={0,1}
Enable 'Hot Edge'*The meta data element is shown when the mouse cursor gets close to the left screen edge, or through the option in the main menu, or through a shortcut. Triggering it using the mouse along the screen edge (the 'hot edge') can be disabled leaving the other two options for showing the element.

// Entry in CONFIG_DIR/settings.db:
  • / MetadataEnableHotEdge={0,1}
GPS Online MapIf the image includes a GPS location, then a click on the location text will load this location in an online map using the default external browser. Here the online service to be used can be chosen (suggestions for other online maps are always welcome).

// Entry in CONFIG_DIR/settings.db:
  • / MetaGpsMapService={openstreetmap.org, maps.google.com, bing.com/maps}
Opacity*By default, the metadata widget is overlapping the main image, thus you might prefer a different alpha value for opacity to increase/decrease readability. Values can be in the range of 0-255.

// Entry in CONFIG_DIR/settings.db:
  • / MetadataOpacity={0-220-255}
Auto-Rotation*Some cameras can detect - while taking the photo - whether the camera was rotated and might store this information in the image meta data. If this information is found PhotoQt can automatically rotate the image accordingly.

// Entry in CONFIG_DIR/settings.db:
  • / MetaApplyRotation={0, 1}
Face TagsIt is possible to store information about detected faces in the meta data. PhotoQt can show markers around those faces and the respective names. It is also possible to tag faces using PhotoQt.

// Entry in CONFIG_DIR/settings.db:
  • / PeopleTagInMetaDisplay={0,1}
Face Tags - Font Size*This is the font size of a name corresponding to a face tag.

// Entry in CONFIG_DIR/settings.db:
  • / PeopleTagInMetaFontSize={5-10-50}
Face Tags - Border*PhotoQt can draw a border around the stored faces. The size and color of that border can also be adjusted.

// Entry in CONFIG_DIR/settings.db:
  • / PeopleTagInMetaBorderAroundFace={0,1}
  • / PeopleTagInMetaBorderAroundFaceWidth={1-3-20}
  • / PeopleTagInMetaBorderAroundFaceColor=#44ff0000
Face tags - VisibilityThere are different modes in which the stored face tags can be shown. The modes are:
  1. hybrid mode: Show all face tags when mouse cursor is not above any one of them. Once the mouse cursor is above a face tag, all the other tags are hidden to highlight the hovered one.
  2. always show all: all face tags are always visible
  3. show one on hover: a face tag is only visible if the mouse is hovering it
  4. show all on hover: all face tags are shown when the mouse cursor is hovering the main image anywhere

// Entry in CONFIG_DIR/settings.db:
  • / PeopleTagInMetaHybridMode={0,1}
  • / PeopleTagInMetaAlwaysVisible={0,1}
  • / PeopleTagInMetaIndependentLabels={0,1}