Nautilus - Thumbnailer for Ms Office documents



When you use Gnome Shell under Ubuntu or Debian, all Ms Office files are displayed thru some generic icons in Nautilus.

With the help of LibreOffice, it is possible to use the first page of a document as a Nautilus thumbnail.

To make it even more visual, the thumbnail can be outdrawn by the document type official icon. You will then get a display much more visual.

This article explains all the steps needed to configure Nautilus to display thumbnails of Ms Office documents including document type icon and first page content, providing a simple and efficient Ms Office documents preview. It is using LibreOffice as a conversion tool and some very basic tools.

This procedure has been tested under Ubuntu 18.10, Ubuntu 18.04 LTS and Ubuntu Gnome 16.04 LTS. It should be applicable to many Gnome based distributions.

Here is the display you get in Nautilus with the generic icons :


And, here is the display you will get with the OpenOffice thumbnailer active :


If you just want to install the MsOffice thumbnailer on your system, without any specific explanation, you can jump to Thumbnailer Installation.

1. Pre-requisite

The thumbnailer script uses different tools :

  • libreoffice (provided by LibreOffice standard installation)
  • mimetype (to determine Office file type)
  • pbmmake, pngtopnm, pnmtopng, pnmscalefixed and pnmcomp (graphic tools from netpbm package)

All these tools can be easily installed under Ubuntu :

# sudo apt-get install libfile-mimeinfo-perl unzip netpbm

2. Thumbnailer Script

When Nautilus needs to generate a thumbnail for a file, it is calling a 'thumbnailer'.

This program (or script) is in charge of generating the thumbnail in a PNG format with a given height.

As Ms Office files are not providing an embedded thumbnail, thumbnail generation is done following few steps :

  1. convert first document page to PNG
  2. Get document mimetype
  3. Determine icon mask accordingly
  4. Transform the PNG applying the specific mask
  5. Resize final image to the thumbnail size provided by Nautilus

Document 1st page conversion is handled by LibreOffice in headless mode. This mode allows libreoffice binary to be called in console mode without any GUI.  To avoid any conflict with a running graphical instance of LibreOffice, binary is called in a temporary user environment to do the conversion.

The following script is the Ms Office document thumbnailer in charge of this task.

#!/usr/bin/env bash
# ---------------------------------------------------
# Thumbnailer for Ms Office documents
# Procedure :
# Depends on :
#   * libreoffice
#   * mimetype (libfile-mimeinfo-perl package)
#   * pbmmake, pngtopnm, pnmtopng, pnmscalefixed and pnmcomp (netpbm package)
# Parameters :
#   $1 - path of office file
#   $2 - path of generated thumbnail
#   $3 - height of thumbnail in pixels
# Revision history :
# 11/11/2014, V1.0 - Creation by N. Bernaerts
# 15/11/2014, V2.0 - Change to URI and GVFS to handle thumbnails on network shares
# 31/07/2015, V2.1 - More robust unoconv command line (thanks to Vaderqk)
# 07/10/2017, V2.2 - Speedup with netpbm tools
# 10/03/2018, V3.0 - Switch from unoconv to libreoffice in headless mode
# 15/03/2018, V3.1 - Handle libreoffice and soffice binaries
# 09/12/2018, V3.2 - Rework for bubblewrap compatibility (thanks to Li Chong)
# ---------------------------------------------------

# check libreoffice availability (binary can be either libreoffice or soffice)
command -v "${CMD_OFFICE}" >/dev/null 2>&1 || CMD_OFFICE="soffice"
command -v "${CMD_OFFICE}" >/dev/null 2>&1 || { echo "[error] libreoffice missing"; exit 1; }

# check tools availability
command -v pbmmake >/dev/null 2>&1 || { echo "[error] pbmmake missing"; exit 1; }
command -v pngtopnm >/dev/null 2>&1 || { echo "[error] pngtopnm missing"; exit 1; }
command -v pnmscalefixed >/dev/null 2>&1 || { echo "[error] pnmscalefixed missing"; exit 1; }
command -v pnmcomp >/dev/null 2>&1 || { echo "[error] pnmcomp missing"; exit 1; }
command -v pnmtopng >/dev/null 2>&1 || { echo "[error] pnmtopng missing"; exit 1; }

# check params
[ "$3" = "" ] && { echo "[error] 3 params are needed : file file-thumb thumb-size"; exit 1; }

# get parameters

# set working path
[ ! -d "${PATH_SYSTEM}" ] && { echo "[error] directory ${PATH_SYSTEM} missing"; exit 1; }

# generate temporary files and directory
TMP_DIR=$(mktemp -t -d "thumb-ms-XXXXXXXX")

# get the file mime type (application/msword, ...)
MIMETYPE=$(mimetype -b "${FILE_LOCAL}")

# determine icon type according to mime type
case ${MIMETYPE} in

    # text
    "application/msword" | \
    "application/" | \
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document" )

    # spreadsheet
    "application/" | \
    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | \
    "application/vnd.openxmlformats-officedocument.spreadsheetml.template" )

    # presentation
    "application/" | \
    "application/vnd.openxmlformats-officedocument.presentationml.presentation" | \
    "application/vnd.openxmlformats-officedocument.presentationml.template" | \
    "application/vnd.openxmlformats-officedocument.presentationml.slideshow" )

    * )

# get document tag and mask

# convert first page to PNG
${CMD_OFFICE} "-env:UserInstallation=file://${TMP_DIR}" --headless --convert-to png --outdir "${TMP_DIR}" "${FILE_LOCAL}"

# convert PNG to PNM
FILE_NAME=$(basename "${FILE_LOCAL}")
pngtopnm "${TMP_DIR}/${FILE_NAME}.png" | pnmscalefixed -xysize 256 256 - > "${TMP_PNM}"

# generate 256x256 thumbnail with masks
pbmmake -white 188 256 | pnmcomp -xoff 2 -yoff=52 "${TMP_PNM}" - | pnmcomp -align left -valign top -alpha "${DOC_ALPHA}" "${DOC_TAG}" - > "${TMP_THUMB}"

# downscale to final size and convert to png
pnmscalefixed -xysize ${SIZE} ${SIZE} "${TMP_THUMB}" | pnmtopng -downscale - > "${FILE_THUMB}"

# remove temporary directory
rm -r "${TMP_DIR}"

It is using some icons available from my GitHub repository that need to be stored under /usr/local/sbin/msoffice-thumbnailer.res :

  • msoffice-odt.png
  • msoffice-ods.png
  • msoffice-odp.png

All these icons are used by the thumbnailer script.

3. Thumbnailer Integration

To allow Nautilus to use the proper thumbnailer for Ms Office documents, you need to declare the previous script as the thumbnailer for all the mime type of these documents (application/msword, ...).

MSDN is providing an exhaustive list of Ms Office documents mime types.

This declaration is done via a msoffice.thumbnailer file placed under /usr/share/thumbnailers. This file follows a specific format, where association between the mime type and the thumbnailer is done.

A complete description of this file format is available from Gnome Developers site on the page Installing a Thumbnailer Program.

With latest Nautilus version, GVFS allows to acccess files located on a network share thru a local path. So, even remote files will get their thumbnails generated.

[Thumbnailer Entry]
Exec=/bin/bash /usr/local/sbin/msoffice-thumbnailer %i %o %s

4. Bubblewrap patch

Under latest gnome version, all thumbnails are generated using bubblewrap sandboxing. But under Ubuntu 18.04, there is a bug in default gnome bwrap parameters, and thumbnails are not generated.

So to solve the problem, you need to declare a local bwrap proxy script which will modifiy the erroneous parameters and call original bwrap. This bwrap proxy script is available from my GitHub repository.

#!/usr/bin/env bash
# bwrap wrapper to correct nautilus 3.26.4+ bug for external thumbnailers under debian based distros
#  * add --ro-bind needed by imagemagick tools
#  * replaces --symlink calls with equivalent --ro-bind calls

# intialise parameters array

# since editing /usr/local/bin requires root privilege, we can trust it
[ -d "/usr/local/bin" ] && ARR_PARAM=( "${ARR_PARAM[@]}" "--ro-bind" "/usr/local/bin" "/usr/local/bin" )

# add both --ro-bind needed by thumbnailers using imagemagick tools
[ -d "/etc/alternatives" ] && ARR_PARAM=( "${ARR_PARAM[@]}" "--ro-bind" "/etc/alternatives" "/etc/alternatives" )
[ -d "/etc/ImageMagick-6" ] && ARR_PARAM=( "${ARR_PARAM[@]}" "--ro-bind" "/etc/ImageMagick-6" "/etc/ImageMagick-6" )
[ -d "/var/cache/fontconfig" ] && ARR_PARAM=( "${ARR_PARAM[@]}" "--ro-bind" "/var/cache/fontconfig" "/var/cache/fontconfig" )

# if exists, enable $TMPDIR
[ -n "${TMPDIR}" ] && [ -d "${TMPDIR}" ] && ARR_PARAM=( "${ARR_PARAM[@]}" "--bind" "${TMPDIR}" "${TMPDIR}" )

# loop thru original parameters
while test $# -gt 0
    case "$1" in
        # --symlink : convert to --ro-bind
        "--symlink") shift; shift; ARR_PARAM=( "${ARR_PARAM[@]}" "--ro-bind" "$1" "$1" ); shift; ;;
        # others : add parameter
        *) ARR_PARAM=( "${ARR_PARAM[@]}" "$1" ); shift; ;;

# call original bwrap
/usr/bin/bwrap "${ARR_PARAM[@]}"

You can install it with these simple commands :

# sudo wget -O /usr/local/bin/bwrap
sudo chmod +rx /usr/local/bin/bwrap

5. Thumbnailer Installation

A simple and complete installation script for MsOffice thumbnailer is available from my GitHub repository.

So, installation can be done with these simple quite easily :

# wget
# chmod +x
# ./

Your old thumbnails should have been purged. Restart nautilus ... you should see your new thumbnails coming.

You can now enjoy to see your Ms Office documents displayed as thumbnails.

As it is using LibreOffice conversion engine, generation may take few seconds.

Hope it helps.

Signature Technoblog

This article is published "as is", without any warranty that it will work for your specific need.
If you think this article needs some complement, or simply if you think it saved you lots of time & trouble,
just let me know at This email address is being protected from spambots. You need JavaScript enabled to view it.. Cheers !

icon linux icon debian icon apache icon mysql icon php icon piwik icon googleplus