3MF Thumbnailer

A thumbnail generator for .3mf files on Ubuntu/Debian, enabling file managers like Nautilus, Thunar, and Nemo to display embedded preview images from 3MF archives (BambuLab, Prusa, and standard 3MF files).

How it works

3MF files are ZIP archives that may embed PNG preview images at well-known paths. The thumbnailer searches for images in the following priority order:

Priority	Path in archive	Typical size
1	Auxiliaries/.thumbnails/thumbnail_middle.png	680×510
2	Metadata/plate_1.png	512×512
3	Auxiliaries/.thumbnails/thumbnail_small.png	~251×188
4	Auxiliaries/.thumbnails/thumbnail_3mf.png	240×180
5	First *.png found anywhere in the archive	—

The extracted image is resized proportionally to the requested thumbnail size using Pillow (LANCZOS resampling) and written as a PNG file.

Files

File	Description
3mf-thumbnailer.py	Python script that extracts and resizes the thumbnail
3mf.thumbnailer	Desktop thumbnailer entry file (read by GNOME/GTK file managers)
install-3mf-thumbnailer.sh	Installation script (requires root)

Requirements

• Python 3
• Pillow (python3-pil or pip3 install Pillow)
• Ubuntu / Debian (or any distro using the XDG thumbnailer system)

Installation

Run the install script with root privileges:

sudo bash install-3mf-thumbnailer.sh

The script will:

1. Install Pillow if not already present.
2. Register the model/3mf MIME type in /usr/share/mime/packages/.
3. Install 3mf-thumbnailer to /usr/local/bin/.
4. Install 3mf.thumbnailer to /usr/share/thumbnailers/.
5. On Ubuntu 24.04+, create an AppArmor profile to allow Nautilus to create user namespaces for the bubblewrap sandbox used by gnome-desktop (required because apparmor_restrict_unprivileged_userns=1 is enabled by default).
6. Clear the current user's thumbnail cache to force regeneration.

After installation, restart Nautilus:

nautilus -q && nautilus &

Or simply log out and back in.

Manual usage

The thumbnailer can also be invoked directly:

3mf-thumbnailer.py <input.3mf> <output.png> <max_size>

Example — generate a 256×256 thumbnail:

python3 3mf-thumbnailer.py model.3mf preview.png 256

MIME types handled

The thumbnailer registers for the following MIME types:

• model/3mf
• application/vnd.ms-3mfdocument
• application/x-3mf

---

License

MIT License