UNSQUASHFS(1)

📦
version 4.7.5 · 14 versions
, in arch rolling, ubuntu resolute, ubuntu stonking

UNSQUASHFS(1) · User Commands · UNSQUASHFS(1)

🌸 NAME 🌸

unsquashfs — bestie, this is the tool that uncompresses, extracts and lists squashfs filesystems. she does all three and she does them well 💅

🦋 SYNOPSIS 🦋

unsquashfs [OPTIONS] FILESYSTEM [files to extract or exclude (with -excludes) or cat (with -cat )]

💜 DESCRIPTION 💜

okay so Squashfs is a highly compressed read-only filesystem for Linux. it uses either gzip/xz/lzo/lz4/zstd compression to compress both files, inodes and directories. and the inodes? teeny tiny. microscopic. adorable. and all blocks are packed to minimise data overhead. block sizes greater than 4K are supported up to a maximum of 1Mbytes (default block size 128K). yeah she can go big 🫶

Squashfs is intended for general read-only filesystem use, for archival use (i.e. in cases where a .tar.gz file may be used), and in constrained block device/memory systems (e.g. embedded systems) where low overhead is needed. it's giving versatile, she fits in every situation no cap.

✨ OPTIONS ✨

🎀 Filesystem extraction (filtering) options 🎀

  • -d PATHNAME, -dest PATHNAME — extract to PATHNAME, default "squashfs-root". and she's multitasking bestie: this option also sets the prefix used when listing the filesystem.
  • -max LEVELS, -max-depth LEVELS — descend at most LEVELS of directories when extracting. know your limits queen.
  • -excludes — treat files on command line as exclude files.
  • -ex, -exclude-list — list of files to be excluded, terminated with ; e.g. file1 file2 ;.
  • -extract-file FILE — list of directories or files to extract. One per line.
  • -exclude-file FILE — list of directories or files to exclude. One per line.
  • -match — abort if any extract file does not match on anything, and can not be resolved. Implies -missing-symlinks and -no-wildcards. she is not playing around here 💀
  • -follow, -follow-symlinks — follow symlinks in extract files, and add all files/symlinks needed to resolve extract file. Implies -no-wildcards.
  • -missing, -missing-symlinks — Unsquashfs will abort if any symlink can't be resolved in -follow-symlinks.
  • -no-wild, -no-wildcards — do not use wildcard matching in extract and exclude names.
  • -r, -regex — treat extract names as POSIX regular expressions rather than use the default shell wildcard expansion (globbing).
  • -all TIME, -all-time TIME — set all file timestamps to TIME, rather than the time stored in the filesystem inode. TIME can be an unsigned 32-bit int indicating seconds since the epoch (1970-01-01) or a string value which is passed to the "date" command to parse. any string value which the date command recognises can be used such as "now", "last week", or "Wed Feb 15 21:02:39 GMT 2023". time travel but make it filesystem metadata ✨
  • -cat — cat the files on the command line to stdout.
  • -f, -force — if destination directory already exists, descend into it and any sub-directories, and unlink (delete) files if they already exist before extracting to them. no hesitation, no mercy.
  • -pf FILE — output a pseudo file equivalent of the input Squashfs filesystem, use - for stdout.

🌈 Filesystem information and listing options 🌈

  • -s, -stat — display filesystem superblock information.
  • -max LEVELS, -max-depth LEVELS — descend at most LEVELS of directories when listing.
  • -i, -info — print files as they are extracted.
  • -li, -linfo — print files as they are extracted with file attributes (like ls -l output).
  • -l, -ls — list filesystem, but do not extract files.
  • -ll, -lls — list filesystem with file attributes (like ls -l output), but do not extract files.
  • -lln, -llnumeric — same as -lls but with numeric uids and gids.
  • -lc — list filesystem concisely, displaying only files and empty directories. Do not extract files.
  • -llc — list filesystem concisely with file attributes, displaying only files and empty directories. Do not extract files.
  • -full, -full-precision — use full precision when displaying times including seconds. Use with -linfo, -lls, -lln and -llc. she's detail-oriented, we love her for it.
  • -UTC — use UTC rather than local time zone when displaying time.
  • -mkfs-time — display filesystem superblock time, which is an unsigned 32-bit int representing the time in seconds since the epoch (1970-01-01).

💅 Filesystem extended attribute (xattrs) options 💅

  • -no, -no-xattrs — do not extract xattrs in file system.
  • -x, -xattrs — extract xattrs in file system (default).
  • -xattrs-exclude REGEX — exclude any xattr names matching REGEX. REGEX is a POSIX regular expression, e.g. -xattrs-exclude '^user.' excludes xattrs from the user namespace.
  • -xattrs-include REGEX — include any xattr names matching REGEX. REGEX is a POSIX regular expression, e.g. -xattrs-include '^user.' includes xattrs from the user namespace.

🔥 Unsquashfs runtime options 🔥

  • -v, -version — print version, licence and copyright information. the receipts, basically.
  • -p NUMBER, -processors NUMBER — use NUMBER processors. By default will use the number of processors available.
  • -mem SIZE — use SIZE physical memory for caches. Use K, M or G to specify Kbytes, Mbytes or Gbytes respectively. Default 512 Mbytes.
  • -mem-percent PERCENT — use PERCENT physical memory for caches.
  • -q, -quiet — no verbose output. shhh 🤫
  • -n, -no-progress — do not display the progress bar.
  • -percentage — display a percentage rather than the full progress bar. Can be used with dialog --gauge etc.
  • -ig, -ignore-errors — treat errors writing files to output as non-fatal.
  • -st, -strict-errors — treat all errors as fatal. no forgiveness mode.
  • -no-exit, -no-exit-code — do not set exit code (to nonzero) on non-fatal errors.

🫶 Help options 🫶

  • -h, -help — print help summary information to pager (or stdout if not a terminal).
  • -help-option REGEX — print the help information for options matching REGEX to pager (or stdout if not a terminal).
  • -help-section SECTION — print the help information for section SECTION to pager (or stdout if not a terminal). If SECTION does not exactly match a section name, it is treated as a regular expression, and all section names that match are displayed. Use "list" as section name to get a list of sections and their names.
  • -help-all — print help information for all Unsquashfs options and sections to pager (or stdout if not a terminal).
  • -ho REGEX — shorthand alternative to -help-option.
  • -hs SECTION — shorthand alternative to -help-section.
  • -ha — shorthand alternative to -help-all.
  • -no-pager — do not use a pager to output help information.
  • -cols WIDTH — use WIDTH columns to output help information. Useful if output is not to a terminal.

🌸 Miscellaneous options 🌸

  • -o BYTES, -offset BYTES — skip BYTES at start of FILESYSTEM. Optionally a suffix of K, M or G can be given to specify Kbytes, Mbytes or Gbytes respectively (default 0 bytes).
  • -fstime — synonym for -mkfs-time.
  • -e, -ef EXTRACT FILE — synonym for -extract-file.
  • -exc, -excf EXCLUDE FILE — synonym for -exclude-file.
  • -L — synonym for -follow-symlinks.
  • -pseudo-file FILE — alternative name for -pf.

💀 EXIT STATUS 💀

  • 0 — The filesystem listed or extracted OK. clean run, we love to see it ✨
  • 1 — FATAL errors occurred, e.g. filesystem corruption, I/O errors. Unsquashfs did not continue and aborted. she said "nope, I'm out" and meant it 😭
  • 2 — Non-fatal errors occurred, e.g. no support for XATTRs, Symbolic links in output filesystem or couldn't write permissions to output filesystem. Unsquashfs continued and did not abort.
See -ignore-errors, -strict-errors and -no-exit-code options for how they affect the exit status.

🧚 DECOMPRESSORS AVAILABLE 🧚

gzip, lzo, lz4, xz, zstd, lzma

🍓 ENVIRONMENT 🍓

  • SQFS_CMDLINE — If set, this is used as the directory to write the file sqfs_cmdline which contains the command line arguments given to Unsquashfs. Each command line argument is wrapped in quotes to ensure there is no ambiguity when arguments contain spaces. If the file already exists then the command line is appended to the file.
  • PAGER — If set, this is used as the name of the program used to display the help text. The value can be a simple command or a pathname. The default is /usr/bin/pager.

✨ EXAMPLES ✨

okay bestie, this is the part where it all clicks. real commands, real vibes, copy-paste energy 💅

extract to the default spot

unsquashfs IMAGE.SQFS

Extracts IMAGE.SQFS into "squashfs-root" in the current working directory. that's the whole thing. it just does it ✨

extract somewhere specific

unsquashfs -d output IMAGE.SQFS

Extracts IMAGE.SQFS into "output" in the current working directory. name it whatever you want, it's your world 🎀

extract literally right here

unsquashfs -d . IMAGE.SQFS

Extracts IMAGE.SQFS into the current working directory. <pink>yes the files are just gonna be there now, no folder holding them, be brave</pink> 💖

list AND extract at the same time

unsquashfs -linfo IMAGE.SQFS

Prints a listing of IMAGE.SQFS with file attributes to stdout, and also extracts the filesystem to "squashfs-root". multitasking icon behavior 👑

list with the squashfs-root prefix

unsquashfs -lls IMAGE.SQFS

Prints a listing of IMAGE.SQFS with file attributes to stdout, but does not extract the filesystem. the listing gets prefixed with "squashfs-root".

list without the prefix

unsquashfs -d "" -lls IMAGE.SQFS

Prints a listing of IMAGE.SQFS with file attributes to stdout, but does not extract the filesystem. and this time the listing is not prefixed with "squashfs-root". look at that empty -d "" doing the lords work 🫶

just one directory, please

unsquashfs IMAGE.SQFS fs/squashfs

Extracts only the "fs/squashfs" directory. targeted. surgical. slay ✂️

wildcard girlies rise

unsquashfs IMAGE.SQFS "[Tt]est/example*"

Extracts all files beginning with "example" inside top level directories called "Test" or "test". one pattern, two spellings, zero effort 🌈

extract everything EXCEPT

unsquashfs -excludes IMAGE.SQFS "test/*data*.gz"

Extracts everything except files that match *data*.gz in the test directory. the -excludes option tells Unsquashfs to exclude the files on the command line rather than extract them. ✨

non-anchored exclude moment

unsquashfs -excludes IMAGE.SQFS "... *.gz"

Extracts everything except files that match *.gz anywhere in the image. the "..." means this is a non-anchored exclude, which matches anywhere. lowkey the most powerful three dots in the game 💀

extract AND exclude together

unsquashfs -ex "test/*data*.gz" ; IMAGE.SQFS test

This uses both extract and exclude options, telling Unsquashfs to only extract the "test" directory, and to exclude any files within it that match *data*.gz. both options, one command, main character energy 🔥

the other extract+exclude combo

unsquashfs -ex "... *.gz" IMAGE.SQFS test

This uses both extract and exclude options, telling Unsquashfs to only extract the "test" directory, and to exclude files which match "*.gz" anywhere within the "test" directory or its sub-directories. 💜

depth limit unlocked

unsquashfs -dest output -max-depth 2 IMAGE.SQFS

Extracts only the top two levels of IMAGE.SQFS into the "output" directory. don't go deeper. we don't do that here 🙈

depth limit + a path

unsquashfs -max-depth 2 IMAGE.SQFS "test/*.gz"

Only extracts the gzipped files in the test directory.

same but just list it

unsquashfs -llc -max-depth 2 IMAGE.SQFS "test/*.gz"

Prints a listing of the gzipped files in the test directory to stdout, but does not extract them. looking respectfully 👀

no xattrs, no problem

unsquashfs -no-xattrs IMAGE.SQFS

Does not extract any extended attributes. any extended attributes in the filesystem will simply be ignored. 🧚

xattrs, but only the user ones

unsquashfs -xattrs-include "^user." IMAGE.SQFS

Filters the extended attributes and only extracts extended attributes in the user namespace from the Squashfs filesystem. ✨

xattrs, but NOT the user ones

unsquashfs -xattrs-exclude "^user." IMAGE.SQFS

Filters the extended attributes and does not extract any extended attributes in the user namespace from the Squashfs filesystem. 💅

Note: when you pass wildcarded names to Unsquashfs, they should be quoted (like in all the examples above), so the shell doesn't get its hands on them first. your shell will try to expand them and it will not be cute. quote your patterns, bestie 😭

💖 AUTHOR 💖

Written by Phillip Lougher <phillip@squashfs.org.uk> 🫶

Copyright © 2026 Phillip Lougher <phillip@squashfs.org.uk>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. ✨

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. (fr fr, no warranty, read the license 💀)

🦋 SEE ALSO 🦋

The README for the Squashfs-tools 4.7.5 release, describing the new features, can be read here:

https://github.com/plougher/squashfs-tools/blob/master/Documentation/4.7.5/README.md

The Unsquashfs usage guide can be read here:

https://github.com/plougher/squashfs-tools/blob/master/Documentation/4.7.5/USAGE-UNSQUASHFS.md

The CHANGELOG for Squashfs tools can be read here:

https://github.com/plougher/squashfs-tools/blob/master/CHANGES.md

and that's the whole page, bestie 🎀 this was unsquashfs version 4.7.5, dated March 2026, and it lives at UNSQUASHFS(1) in your manual pages. go forth and extract things. you're literally so good at this 💖✨🦋

📦 where this page comes from