Try "merge pdf", "crop image", "password", "read qr" or "15% of 80".

AppImage Compression: gzip, zstd and xz

The SquashFS superblock inside an AppImage stores one compression ID for the whole image. A runtime can read only the methods it was built with: the current static type 2 runtime reads zlib (gzip) and zstd, the older AppImageKit runtime reads xz and zlib, and appimagetool now builds with zstd by default. An AppImage fails wherever its method is not on the reader’s list.

Where the method is stored

The SquashFS image begins with a 96-byte superblock. The compression field is a 16-bit number at byte 20 of it. Every compressed block of the image, data, fragments and metadata alike, uses that one method, so a reader either has the decompressor or cannot read any file.

Fields of the superblock in the example on the AppImage structure page, read back by UNQIRO’s SquashFS reader when this page was built.
Byte Field Value Meaning
0 s_magic "hsqs" SquashFS signature
12 block_size 131,072 bytes per data block
20 compression 6 zstd, for the whole image
22 block_log 17 log2 of the block size
28 s_major, s_minor 4.0 format version

gzip and zlib are the same method here. mksquashfs calls ID 1 gzip, squashfs_fs.h calls it ZLIB_COMPRESSION, and error messages say zlib.

Which reader reads what

SquashFS compression IDs (squashfs_fs.h) and the AppImage readers that can decompress them. The UNQIRO column is taken from its reader when this page is built.
ID Method Current runtime AppImageKit 13 runtime UNQIRO
1 gzip
ZLIB_COMPRESSION 		Yes Yes Yes
2 lzma
LZMA_COMPRESSION 		No No No
3 lzo
LZO_COMPRESSION 		No No No
4 xz
XZ_COMPRESSION 		No Yes No
5 lz4
LZ4_COMPRESSION 		No No No
6 zstd
ZSTD_COMPRESSION 		Yes No Yes
  • Current runtime. type2-runtime is linked statically against squashfuse, libzstd and zlib. Because it is static, it no longer needs libfuse2 on the system.
  • Older runtime. The runtime of AppImageKit (release 13) is linked against squashfuse, xz and zlib.
  • appimagetool. It uses zstd unless --comp names another method. For zstd it sets a block size of 128 KiB, for xz 16 KiB.
  • UNQIRO. It reads gzip and zstd in the browser and names every other method instead of guessing.

The two error messages

Both come from squashfuse, the SquashFS library these runtimes are built on. It prints the image’s method and then the list of methods it was built with.

“uses xz compression, this version supports only zlib, zstd”

Squashfs image uses xz compression, this version supports only zlib, zstd.

An xz image met a reader built only with zlib and zstd, as the current runtime is. The AppImage catalog’s automated check reported exactly this for an xz image.

“uses (null) compression, this version supports only xz, zlib”

Squashfs image uses (null) compression, this version supports only xz, zlib.

This is older squashfuse code. Its table of method names ends at lz4 (ID 5), so it prints (null) for an ID it has no name for. Of the methods SquashFS defines, only zstd (ID 6) is printed this way: a zstd image met a reader built with xz and zlib only. The message has been reported, for example, with AppImageLauncher 2.2.0.

Why an AppImage works on one system and fails on another

The method is fixed when the AppImage is built, but the reader is not always the AppImage’s own runtime. Starting the file uses the runtime embedded in it. Tools that open or integrate AppImages themselves, thumbnailers and catalog checks bring their own SquashFS code, built with their own list of methods.

So a zstd AppImage can start with its own current runtime and still fail in a tool built on older squashfuse. The reverse happens too: an xz AppImage fails in a reader built only with zlib and zstd.

Other methods and DwarFS in UNQIRO

For an image compressed with lzma, lzo, xz and lz4, UNQIRO stops after the superblock, before reading any file, and names the method:

This AppImage is compressed with xz, which this tool cannot read yet. AppImages compressed with zstd or gzip work.

Some runtimes, such as uruntime, can also carry a DwarFS image instead of SquashFS. UNQIRO recognizes the DwarFS signature where the image starts and says that it cannot read that file system yet.

What to do

If you use the AppImage: the message names the image’s method and the reader’s list. A tool that fails may simply be older than the AppImage; starting the AppImage itself uses its own runtime. If you build AppImages: appimagetool’s default, zstd, matches the current runtime, and zlib (--comp gzip) is on the list of both runtimes in the table.

Check your own file

The AppImage tool reads the superblock of your AppImage in the browser. Its technical details show the file system and compression, and a method it cannot read is named instead. The AppImage is not run and not uploaded.

Check which compression your AppImage uses (AppImage Icon Extractor)

Sources