Extract and Inspect Squashfs Images Safely with unsquashfs

Somebody handed you a firmware blob or a Snap package and unsquashfs is what actually gets inside it, no full extraction required just to look. You will inspect a Squashfs image, then pull out either the whole thing or a controlled selection into a directory you choose. The examples use unsquashfs 4.6.1 from the Debian package squashfs-tools 1:4.6.1-1build1.

Allow about fifteen minutes. You need a shell, a Squashfs image, and enough free space for whatever you plan to extract. The commands below are ordinary user commands. Use sudo only if the destination or image permissions genuinely require it, and do not extract an untrusted image into a directory containing valuable files.

1. Confirm the installed tool

Check the binary and version before relying on option details. This is read-only and does not need elevated privileges:

$ command -v unsquashfs
/usr/bin/unsquashfs
$ unsquashfs -version
unsquashfs version 4.6.1 (2023/03/25)

2. Inspect before extracting

Set a placeholder for your image, then ask for filesystem statistics:

$ IMAGE='/path/to/image.sqfs'
$ unsquashfs -stat "$IMAGE"
Found a valid SQUASHFS 4:... filesystem on ...
Filesystem size ...
Block size ...
Compression ...

The exact lines and values depend on the image. A successful inspection returns status 0. A corrupt image or an I/O failure is fatal and returns status 1. Capture the status immediately when scripting:

$ unsquashfs -stat "$IMAGE"
$ status=$?
$ printf 'unsquashfs status: %s\n' "$status"

Do not use a successful statistic check as proof that every file will extract correctly. It checks the filesystem metadata; the destination still needs space and write permission.

3. List files without writing them

Use -ls or its long form -lls to list the image without extracting anything:

$ unsquashfs -lls "$IMAGE"
drwxr-xr-x root/root                 0 2026-01-01 12:00 squashfs-root/
-rw-r--r-- root/root                18 2026-01-01 12:00 squashfs-root/etc/example.conf

The timestamps, owners and paths are image-specific. The listing normally prefixes paths with squashfs-root, even though no directory has been created. If that prefix would make a later comparison awkward, pass an empty destination:

$ unsquashfs -d '' -lls "$IMAGE"
drwxr-xr-x root/root                 0 2026-01-01 12:00 /
-rw-r--r-- root/root                18 2026-01-01 12:00 /etc/example.conf

Use -llnumeric when numeric user and group IDs are more useful than names. Use -UTC when you need displayed times to be independent of the local timezone.

4. Extract into an empty destination

Choose a new destination explicitly. The default is a directory called squashfs-root in the current directory, which is easy to overlook and easy to collide with:

$ DEST='/tmp/squashfs-review'
$ mkdir "$DEST"
$ unsquashfs -dest "$DEST" "$IMAGE"
Parallel unsquashfs: Using ... processors
... files written
$ find "$DEST" -maxdepth 2 -print | head

Output counts and progress vary with the image and terminal. The destination is created or populated by the command. If a file already exists, unsquashfs does not overwrite it by default. That protects an existing tree, but it also means a partially populated destination can produce a non-fatal error.

5. Extract only what you need

Put image paths after the image name to select files or directories:

$ DEST='/tmp/squashfs-selected'
$ mkdir "$DEST"
$ unsquashfs -dest "$DEST" "$IMAGE" etc/example.conf usr/share/example

Selection names use shell-style wildcard matching by default. Quote wildcard expressions so your shell does not expand them against the host filesystem:

$ unsquashfs -dest "$DEST" "$IMAGE" 'usr/share/example/*.conf'

Use -regex when the selection should be a POSIX regular expression. Use -no-wildcards when names must be matched literally. -max-depth 2 limits how far unsquashfs descends while extracting or listing.

For repeatable selections, put one path per line in a file and pass it to -extract-file:

$ printf '%s\n' etc/example.conf usr/share/example > /tmp/squashfs-files.txt
$ unsquashfs -dest "$DEST" -extract-file /tmp/squashfs-files.txt "$IMAGE"

Review that file before running the command. It controls what is written to the destination. Remove the temporary list afterwards if it contains sensitive paths:

$ rm -- /tmp/squashfs-files.txt

6. Handle metadata and errors deliberately

Extended attributes are extracted by default. Use -no-xattrs when the destination filesystem or your review process should not receive them. To keep only a namespace, use a POSIX regular expression:

$ unsquashfs -dest "$DEST" -xattrs-include '^user\.' "$IMAGE"

Some metadata cannot be reproduced by an ordinary user. The documented exit statuses separate fatal and non-fatal problems:

• 0: the image was listed or extracted successfully.
• 1: a fatal error occurred, such as corruption or an I/O failure.
• 2: a non-fatal error occurred and extraction continued, such as unsupported extended attributes or permissions that could not be written.

Use -strict-errors when a non-fatal error must fail the operation. Use -ignore-errors only when partial output is acceptable and your caller records that fact. -no-exit-code suppresses a non-zero status for non-fatal errors, which can hide incomplete output, so reserve it for a caller that has another reliable result check.

If a symlink in a selection must be followed, -follow-symlinks changes how that selection is resolved. Combine it with -missing-symlinks when an unresolved link must abort. Treat this as a path-selection decision: inspect the image first and do not follow links merely to make a missing path appear.

7. Verify the result and clean up

Check the command status, inspect the files you expected, and compare a listing with the source image:

$ unsquashfs -dest "$DEST" "$IMAGE" 'etc/example.conf'
$ status=$?
$ printf 'status: %s\n' "$status"
$ test -f "$DEST/etc/example.conf" && printf '%s\n' 'selected file present'

A status of 2 means the check needs a decision, not an automatic success label. Preserve the extracted tree if it is evidence. Otherwise remove the exact temporary directory when you have finished:

$ rm -rf -- /tmp/squashfs-selected

That removal is irreversible. Confirm DEST points to the temporary extraction directory before running it. For a destination outside /tmp, use your normal backup and change-control process instead.