Migrating from the Gtk Version to Qt#

Some time ago I decided to rewrite vimiv completely in Qt because I was not happy with the Gtk version and the source code. For some more details, you can check the corresponding issue on github.

Besides the maintenance improvements for me and cleaner code + tests which should make contributing easier, there were a number of major improvements and new feature including:

  • Much better performance, especially in thumbnail mode.

  • Complete customization with styles.

  • The possibility to bind key sequences like gg.

  • A keyhint widget popping up after 500 ms to help you with finding the missing part of key sequences.

  • Customization of the statusbar with status modules.

  • A plugin system enabling print support.

  • Automatic reload when the image / directory was changed from the outside.

  • Better synchronization between the various modes.

Overall I hope that the improvements of the Qt version outweigh the inconvenience of a lot of breaking changes. The following sections summarize some of the major changes to give you a feeling of what will break when migrating. If you have any questions or need help, please do not hesitate to open an issue on github or contact me directly.

Major Changes#

Key Sequences#

It is now possible to bind key sequences like gg. This possibility changed the default bindings for switching modes. The library is entered with gl and toggled with tl. Same holds for thumbnail and manipulate mode with t as suffix instead of l. Image mode can only be entered with gi, not toggled, as it is the “normal” mode of vimiv. To help you with partial matches, a keyhint widget pops up 500 ms after the first key press.

Keybinding Names#

  • Naming of modifiers has changed to account for key sequences and for consistency.

    • Shift+ is largely replaced by the actual character, e.g. Shift+w becomes W. Where this is not possible, use <shift>, e.g. <shift><tab>.

    • ^q becomes <ctrl>q.

    • Alt+l becomes <alt>l.

  • If keys have a string representation, this is their keybinding. So +, / and so forth are the valid keybindings, not plus or slash. Only exceptions are <colon> for : and <equal> for = as these are valid separators for the configuration file.

  • Special keys with no string representation are always surrounded in <> brackets and are lower-case. Therefore Escape becomes <escape>, Return <return> and so forth.


If you want to figure out the name of a specific key or mouse button, run vimiv with --debug gui.eventhandler. You can find the corresponding name in the first output line after pressing/clicking it. For example, when pressing the q key, you would retrieve something along:

DEBUG    <gui.eventhandler>   EventHandlerMixin: handling q for mode library

Command Names#

Command handling has been redesigned for better scalability. This means that many names and/or arguments have changed. You can find a complete overview of the current commands in the documentation. If you have trouble finding out how a previous command changed or are missing something, please do not hesitate to open an issue on github or contact me directly.


The rewrite has been used to rethink various settings. I hope the names are now clearer and the handling is more consistent. This is a brief overview of what happened to the settings that were available in the gtk version. The word before the . indicates the section, the one after is the option name.

Overview of settings changes#




Removed, use the --fullscreen command line flag instead


Removed, use --command slideshow instead


Moved to slideshow.delay


Moved to sort.shuffle


Moved to statusbar.show


Moved to thumbnail.size


Removed, use --geometry instead


Removed, use the corresponding shell tools instead


Removed, this is always done as it is now performant


Moved to image.overzoom


Moved to search.ignore_case


Moved to search.incremental


Removed, the :copy-name command has an optional --primary flag instead


Removed, use styles instead


Removed, use styles instead


Removed, use styles instead


Moved to image.autoplay


Moved to general.startup_library


Removed, use styles instead


Removed, please open an issue if you miss this feature


Removed, use styles instead


Removed, use styles instead


Remains the same


Removed, please open an issue if you miss this feature


Removed, we use the total number of files instead


Moved to statusbar.collapse_home


Moved to image.autowrite

Marks and Tags#

Your tag files are migrated and should continue working as is. However, the behaviour of marks and tags has changed in some ways.

  • The :mark command can now take any number of paths as argument. This includes typical shell wildcards and replaces the unorthodox behaviour of :mark-between. To mark a list of images, pass them or the corresponding wildcard to :mark, e.g.:

    :mark images_1*.jpg
  • The mark command now toggles the mark status of the paths passed. The default binding m is therefore equivalent to the old :mark_toggle bound to M.

  • Calling :tag-load now marks all images in the tag instead of loading them into image mode. To open them in image mode, call :open %m afterwards.


Navigation in manipulate mode has been redesigned for better scalability. The one letter shortcuts to manipulation names were unfortunately rather limiting…

  • To focus the next/previous manipulation in the current tab, use n/p.

  • To focus the next/previous tab, use <tab>/<shift><tab>.


When you first launch the qt version and you had a local vimivrc of the gtk version:

  • All vimiv folders are backed up to vimiv-gtk-backup.

  • Your tags are migrated accordingly.

  • A welcome pop-up with the most important information is shown.