Thumbnails

☶︎

This article or section needs to be expanded. Please consult the pedia article metapage for guidelines on contributing.

Enabling Thumbnailers

On minimal / custom desktop environments thumbnails in file explorers may not work by default. For example:

• GNOME environments with the option services.gnome.core-utilities.enable = false;
• Custom environments built using window managers like sway or hyperland

Enable Video Thumbnails

To enable thumbnails for video files use ffmpeg-headless to decode videos and fmpegthumbnailer to generate thumbnails.

Thumbnails for the following MimeTypes will be enabled: video/jpeg; video/mp4; video/mpeg; video/quicktime; video/x-ms-asf; video/x-ms-wm; video/x-ms-wmv; video/x-ms-asx; video/x-ms-wmx; video/x-ms-wvx; video/x-msvideo; video/x-flv; video/x-matroska; application/x-matroska; application/mxf; video/3gp; video/3gpp; video/dv; video/divx; video/fli; video/flv; video/mp2t; video/mp4v-es; video/msvideo; video/ogg; video/vivo; video/vnd.avi; video/vnd.divx; video/vnd.mpegurl; video/vnd.rn-realvideo; application/vnd.rn-realmedia; video/vnd.vivo; video/webm; video/x-anim; video/x-avi; video/x-flc; video/x-fli; video/x-flic; video/x-m4v; video/x-mpeg; video/x-mpeg2; video/x-nsv; video/x-ogm+ogg; video/x-theora+ogg.

# configuration.nix
{ pkgs, ... }: 
{

  environment.systemPackages = with pkgs; [
    ffmpeg-headless
    ffmpegthumbnailer
  ];

  # 'ffmpegthumbnailer.thumbnailer' is created in '/run/current-system/sw/share/thumbnailers' 
    # but thumbnails are not displayed unless symlinks to 'share/thumbnailers' are also defined

  # uncomment if this has already been defined in your configuration.nix
  environment.pathsToLink = [
    "share/thumbnailers"
  ];

}

Enable Image Thumbnails

To enable thumbnails for image files use gdk-pixbuf to decode images and generate thumbnails.

Thumbnails for the following MimeTypes will be enabled: image/png; image/jpeg; image/bmp; image/x-bmp; image/x-MS-bmp; image/gif; image/x-icon; image/x-ico; image/x-win-bitmap; image/vnd.microsoft.icon; application/ico; image/ico; image/icon; text/ico; image/x-portable-anymap; image/x-portable-bitmap; image/x-portable-graymap; image/x-portable-pixmap; image/tiff; image/x-xpixmap; image/x-xbitmap; image/x-tga; image/x-icns; image/x-quicktime; image/qtif.

# configuration.nix
{ pkgs, ... }: 
{

  environment.systemPackages = with pkgs; [ 
    gdk-pixbuf
  ];

  # 'gdk-pixbuf-thumbnailer.thumbnailer' is created in '/run/current-system/sw/share/thumbnailers' 
    # but thumbnails are not displayed unless symlinks to 'share/thumbnailers' are also defined

  # uncomment if this has already been defined in your configuration.nix
  environment.pathsToLink = [
   "share/thumbnailers"
  ];

}

Enable HEIF Image Thumbnails

To enable thumbnails for HEIF image format use libheif to decode HEIF images and libheif.out to generate thumbnails.

Thumbnails for the following MimeTypes will be enabled: image/heif; image/avif.

# configuration.nix
{ pkgs, ... }: 
{

  environment.systemPackages = with pkgs; [ 
    libheif
    libheif.out
  ];

  # 'heif.thumbnailer' is created in '/run/current-system/sw/share/thumbnailers' 
    # but thumbnails are not displayed unless symlinks to 'share/thumbnailers' are also defined

  # uncomment if this has already been defined in your configuration.nix
  environment.pathsToLink = [
   "share/thumbnailers"
  ];

}

Creating Custom Thumbnailers

Most package mangers accept the Thumbnail Managing Standard, by using it you can create your own thumbnailer for any file format, this can be done by:

1. First you need to figure out how to create a .png image from a file in the desired format.
2. Create a .thumbnailer file in $XDG_DATA_DIRS/thumbnailers.
3. Restart your thumbnailer service (This is specific to each file manager) and test if it's working.

Example

You could create a thumbnailer for Krita's .kra file format like so:

.kra are zip files, with a preview stored at /preview.png, we can use unzip to extract the preview:

unzip -p robot-squirrel.kra preview.png > robot-squirrel.png

Create a .thumbnailer file in any $XDG_DATA_DIRS/thumbnailers directory.

# $HOME/.local/share/thumbnailers/kra.thumbnailer
[Thumbnailer Entry]
Exec=sh -c "unzip -p %i preview.png > %o"
MimeType=application/x-krita;

Restart your thumbnailer service (This is specific to each file manager) and test if it's working.

After you have a working definition, you can make it reproducible like so:

# configuration.nix
{ pkgs, ... }: {
  environment.systemPackages = [
    (
      pkgs.writeTextFile {
        # This can be anything, it's just the name of the derivation in the nix store
        name = "krita-thumbnailer";
        # This is the important part, the path under which this will be installed
        destination = "/share/thumbnailers/kra.thumbnailer";
        # The contents of your thumbnailer, don't forget to specify the full path to executables
        text = ''
          [Thumbnailer Entry]
          Exec=sh -c "${pkgs.unzip}/bin/unzip -p %i preview.png > %o"
          MimeType=application/x-krita;
        '';
      }
    )
  ];
}