Thumbnails

☶︎

This article or section needs to be expanded. Further information may be found in the related discussion page. 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;
        '';
      }
    )
  ];
}