latest version: 2.8
© 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 respective values in the settings config file. The default value is usually shown in bold. The settings file 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.

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.
LabelsPhotoQt shows certain information about the current image and the folder in the top left corner of the screen. You can show/hide the various parts of that information. Additionally, at the top right corner of the screen, some window buttons can be shown/hidden for closing PhotoQt and entering/exiting fullscreen mode.

In order to fine tune the labels from the settings manager the expert mode needs to be enabled first. Otherwise, the default selection of settings is chosen.

// Entry in CONFIG_DIR/settings:
  • LabelsHideCounter={0,1}
  • LabelsHideFilepath={0,1}
  • LabelsHideFilename={0,1}
  • LabelsHideZoomLevel={0,1}
  • LabelsHideRotationAngle={0,1}
  • LabelsWindowButtons={0,1}
  • LabelsWindowButtonsSize={5-10-25}
Window ModePhotoQt can be used just as well in both fullscreen mode and as a normal window.

Note that in window mode, it might be best to combine that option with the popout options for at least some of the elements as they might not be fully visible in small windows.

// Entry in CONFIG_DIR/settings:
  • WindowMode={0,1}
  • WindowDecoration={0,1}
Quick NavigationSome buttons to help with quick navigation. These can come in handy when, e.g., operating with a touch screen.

// Entry in CONFIG_DIR/settings:
  • QuickNavigation={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:
  • 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:
  • BackgroundImageScreenshot={0,1}
  • BackgroundImageUse={0,1}
  • BackgroundImagePath=""
  • BackgroundImageScale={0,1}
  • BackgroundImageScaleCrop={0,1}
  • BackgroundImageStretch={0,1}
  • BackgroundImageCenter={0,1}
  • 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.

// Entry in CONFIG_DIR/settings:
  • BackgroundColorRed={0-255}
  • BackgroundColorGreen={0-255}
  • BackgroundColorBlue={0-255}
  • BackgroundColorAlpha={0-100-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:
  • MainMenuPopoutElement={0,1}
  • MetadataPopoutElement={0,1}
  • HistogramPopoutElement={0,1}
  • ScalePopoutElement={0,1}
  • OpenPopoutElement={0,1}
  • OpenPopoutElementKeepOpen={0,1}
  • SlideShowSettingsPopoutElement={0,1}
  • SlideShowControlsPopoutElement={0,1}
  • FileRenamePopoutElement={0,1}
  • FileDeletePopoutElement={0,1}
  • AboutPopoutElement={0,1}
  • ImgurPopoutElement={0,1}
  • WallpaperPopoutElement={0,1}
  • FilterPopoutElement={0,1}
  • SettingsManagerPopoutElement={0,1}
  • FileSaveAsPopoutElement={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:
  • StartupLoadLastLoadedImage={0,1}
Click on Empty AreaThis option makes PhotoQt behave a bit like the JavaScript image viewers you find on many websites. A click outside of the image on the empty background will close the application. This way PhotoQt will feel like a 'floating layer', however, this can easily be triggered accidentally.

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

// Entry in CONFIG_DIR/settings:
  • CloseOnEmptyBackground={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. This setting controls how close to the screen edge you have to get before they are shown.

// Entry in CONFIG_DIR/settings:
  • HotEdgeWidth={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:
  • LabelsManageWindow={0,1}
  • SaveWindowGeometry={0,1}
  • KeepOnTop={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:
  • MouseWheelSensitivity={1-10}
Custom Main Menu EntriesIn the main menu hidden behind the right edge of the main interface, custom menu entries can be added. Each entry requires the text to be shown in the main menu, the executable, and whether to close PhotoQt after execution.

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

Image View
Sort ImagesImages 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:
  • SortImagesBy={name, naturalname, date, size, type}
  • SortImagesAscending={0,1}
Transparency in ImagesTransparency in an image is, by default, shown as 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:
  • ShowTransparencyMarkerBackground={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:
  • 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:
  • LoopThroughFolder={0,1}
Left Mouse Button*By default, the left button can be used to move the image around. This excluded the left button from being used for shortcuts. Disabling this option reverses that situation: The left button will not move the image anymore but can be used for shortcuts.
Margin Around Image*A loaded image is shown across the full screen, from edge to edge. It is possible to add a margin of a few pixels around the image.

// Entry in CONFIG_DIR/settings:
  • MarginAroundImage={0-5-50}
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:
  • PixmapCache={0-512-2048}
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
In addition to the type of animation, its speed can also be adjusted here.

// Entry in CONFIG_DIR/settings:
  • AnimationType={opacity, along x-axis, along y-axis}
  • 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:
  • 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:
  • KeepZoomRotationMirror={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:
  • ZoomSpeed={1-20-100}

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:
  • 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:
  • 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:
  • 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:
  • 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:
  • ThumbnailCenterActive={0,1}
PositionThe thumbnails can be shown either along the lower or upper edge of the window.

// Entry in CONFIG_DIR/settings:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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:
  • PeopleTagInMetaHybridMode={0,1}
  • PeopleTagInMetaAlwaysVisible={0,1}
  • PeopleTagInMetaIndependentLabels={0,1}