SQFSTAR(1)

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

🌸 SQFSTAR — the sqfstar(1) glow-up 💅

okay bestie, welcome to SQFSTAR, a User Command, and it's literally the moment your tar archive becomes a whole entire squashfs filesystem. no cap.

✨ NAME ✨

sqfstar — a tool to create a squashfs filesystem from a tar archive 🎀

🦋 SYNOPSIS 🦋

  cat xxx.tar | sqfstar [OPTIONS] FILESYSTEM [exclude files]
  zcat xxx.tgz | sqfstar [OPTIONS] FILESYSTEM [exclude files]
  xzcat xxx.tar.xz | sqfstar [OPTIONS] FILESYSTEM [exclude files]
  zstdcat xxx.tar.zst | sqfstar [OPTIONS] FILESYSTEM [exclude files]

so basically you pipe a tar into it and it goes brrr into a FILESYSTEM. the way that works is so iconic 🫶

💖 DESCRIPTION 💖

Squashfs is a highly compressed read-only filesystem for Linux, and it's giving main character energy fr fr. It uses either gzip/xz/lzo/lz4/zstd compression to compress both files, inodes and directories. Inodes in the system are very small and all blocks are packed to minimise data overhead. Block sizes greater than 4K are supported up to a maximum of 1Mbytes — and the default block size is 128K, iykyk.

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. lowkey it does it all 💜

⭐ OPTIONS ⭐

🔥 Filesystem compression options:

  • -b BLOCK-SIZE — set data block to BLOCK-SIZE. Default 128 Kbytes. Optionally a suffix of K, KB, Kbytes or M, MB, Mbytes can be given to specify Kbytes or Mbytes respectively.
  • -comp COMP — select COMP compression. Run -help-comp COMP to get compressor options for COMP, or ALL for all the compressors. Compressors available: gzip (default), lzo, lz4, xz, zstd, lzma.
  • -noI — do not compress inode table.
  • -noId — do not compress the uid/gid table (implied by -noI).
  • -noD — do not compress data blocks.
  • -noF — do not compress fragment blocks.
  • -noX — do not compress extended attributes.
  • -no-compression — do not compress any of the data or metadata. This is equivalent to specifying -noI -noD -noF and -noX.

🎀 Filesystem build options:

  • -exports — make the filesystem exportable via NFS.
  • -no-sparse — do not detect sparse files.
  • -no-fragments — do not use fragments.
  • -no-tailends — do not pack tail ends into fragments.
  • -no-duplicates — do not perform duplicate checking.
  • -no-hardlinks — do not hardlink files, instead store duplicates.
  • -regex — allow POSIX regular expressions to be used in exclude dirs/files.
  • -ignore-zeros — allow tar files to be concatenated together and fed to Sqfstar. Normally a tarfile has two consecutive 512 byte blocks filled with zeros which means EOF and Sqfstar will stop reading after the first tar file on encountering them. This option makes Sqfstar ignore the zero filled blocks.
  • -ef EXCLUDE-FILE — list of exclude dirs/files. One per line.

🌈 Filesystem time options:

  • -mkfs-time TIME — set filesystem creation timestamp to TIME. TIME can be "inode", which means use the latest inode timestamp, 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".
  • -inode-time TIME — set all file and directory timestamps to TIME. TIME can be "inode", which means use the latest inode timestamp, 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 2025". This option sets and overrides the -root-time option.
  • -root-time TIME — set root directory time to TIME. TIME can be "inode", which means use the latest inode timestamp, 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 2025".
  • -repro — build a reproducible filesystem image. This is equivalent to -mkfs-time inode, which achieves reproducibility by setting the filesystem build time to the latest inode timestamp. Obviously the image won't be reproducible if the timestamps or content changes.
  • -repro-time TIME — build a reproducible filesystem image. This is equivalent to specifying -mkfs-time TIME and -inode-time TIME, which achieves reproducibility by setting all timestamps to TIME. This option can be used in cases where timestamps may change, and where -repro cannot be used for this reason.

🧚 Filesystem permissions options:

  • -all-root — make all files and directories owned by root.
  • -root-mode MODE — set root directory permissions to MODE. MODE can be symbolic or octal (see section Symbolic mode specification). Default root mode is ugo=rwx or 0777 octal.
  • -root-uid USER — set root directory owner to specified USER, USER can be either an integer uid or user name.
  • -root-gid GROUP — set root directory group to specified GROUP, GROUP can be either an integer gid or group name.
  • -force-file-mode MODE — set all file (non-directory) permissions to MODE. MODE can be symbolic or octal (see section Symbolic mode specification).
  • -force-dir-mode MODE — set all directory permissions to MODE. MODE can be symbolic or octal (see section Symbolic mode specification).
  • -force-uid USER — set all file and directory uids to specified USER, USER can be either an integer uid or user name.
  • -force-gid GROUP — set all file and directory gids to specified GROUP, GROUP can be either an integer gid or group name.
  • -uid-gid-offset VALUE — offset all uid and gids by specified VALUE. VALUE should be a positive integer.
  • -default-mode MODE — tar files often do not store permissions for intermediate directories. This option sets the default directory permissions to MODE. MODE can be symbolic or octal (see section Symbolic mode specification). Default mode is u=rwx,go=rx or 0755 octal. This also sets the root directory mode.
  • -default-uid USER — tar files often do not store uids for intermediate directories. This option sets the default directory owner to USER, rather than the user running Sqfstar. USER can be either an integer uid or user name. This also sets the root directory uid.
  • -default-gid GROUP — tar files often do not store gids for intermediate directories. This option sets the default directory group to GROUP, rather than the group of the user running Sqfstar. GROUP can be either an integer gid or group name. This also sets the root directory gid.
  • -numeric-owner — Use the numeric uid and gid in the tarfile rather than the user name or group name. This is useful where the user name or group name maps to a different uid or gid on the system where Sqfstar is being run, and this remapping behaviour is not wanted.

🍓 Filesystem pseudo options:

  • -p PSEUDO-DEFINITION — add pseudo file definition. The definition should be quoted. See section "Pseudo file definition format" for format details.
  • -pd "d mode uid gid" — specify a default pseudo directory which will be used in pseudo definitions if a directory in the pathname does not exist. This also allows pseudo definitions to be specified without specifying all the directories in the pathname. The definition should be quoted.
  • -pd "D time mode uid gid" — specify a default pseudo directory which will be used in pseudo definitions if a directory in the pathname does not exist. The D type also allows a timestamp to be specified in addition to mode, uid and gid.
  • -pf PSEUDO-FILE — add list of pseudo file definitions. Pseudo file definitions in pseudo-files should not be quoted.
  • -pseudo-override — make pseudo file uids and gids override -all-root, -force-uid and -force-gid options.

💜 Filesystem extended attribute (xattrs) options:

  • -no-xattrs — do not store extended attributes.
  • -xattrs — store extended attributes (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.
  • -xattrs-add NAME=VAL — add the xattr NAME with VAL to files. If an user xattr it will be added to regular files and directories (see man 7 xattr). Otherwise it will be added to all files. VAL by default will be treated as binary (i.e. an uninterpreted byte sequence), but it can be prefixed with 0s, where it will be treated as base64 encoded, or prefixed with 0x, where val will be treated as hexidecimal. Additionally it can be prefixed with 0t where this encoding is similar to binary encoding, except backslashes are specially treated, and a backslash followed by 3 octal digits can be used to encode any ASCII character, which obviously can be used to encode control codes. The option can be repeated multiple times to add multiple xattrs.

👑 Sqfstar runtime options:

  • -version — print version, licence and copyright message.
  • -force — force Sqfstar to write to block device or file.
  • -exit-on-error — treat normally ignored errors as fatal.
  • -quiet — no verbose output.
  • -info — print files written to filesystem to stdout. This automatically disables the progress bar. See -info-file to output to file without disabling the progress bar.
  • -info-file FILE — print files written to filesystem to file FILE. This does not disable the progress bar.
  • -no-progress — do not display the progress bar.
  • -progress — display progress bar when using the -info option.
  • -percentage — display a percentage rather than the full progress bar. Can be used with dialog --gauge etc.
  • -throttle PERCENTAGE — throttle the I/O input rate by the given percentage. This can be used to reduce the I/O and CPU consumption of Sqfstar.
  • -limit PERCENTAGE — caps the I/O input rate at PERCENTAGE percent. basically a lil diet plan for your disk reads 🍓 it trims down Sqfstar's I/O and CPU appetite (it's the alt to -throttle).
  • -processors NUMBER — tells Sqfstar to use NUMBER processors. leave it alone and it'll just grab however many processors you've got, which is usually the move 💅
  • -mem SIZE — use SIZE of physical memory for caches. slap a K, M or G on the end for Kbytes, Mbytes or Gbytes respectively ✨
  • -mem-percent PERCENT — use PERCENT of physical memory for caches. default is 25%.
  • -mem-default — just prints out the default memory usage in Mbytes. a lil peek, no notes 👑
  • -overcommit PERCENT — lets PERCENT more threads run in parallel than you have processors. this might bump your CPU utilisation. default is 0%, because overcommitting normally tanks performance via trashing 😭 and btw the percentage only moves in steps of your processor count — e.g. 4 processors = 25% granularity, 20 processors = 5% granularity.

🚨 Expert options (these may make the filesystem unmountable) 🚨

bestie. read the heading. these may make the filesystem unmountable. do not freestyle here unless you know exactly what you're doing 💀
  • -stream — output the filesystem to STDOUT instead of to a file. this is the girlboss move that lets you pipe the output into another program, or ship it elsewhere with ssh 🦋 the streamed Squashfs filesystem won't be a normal Squashfs filesystem though, because the super block ends up at the end of the filesystem. but you can fix it up after the fact with the -fix option, and Unsquashfs 4.7.3 and later can read streamed unfixed up filesystems directly. also heads up: duplicate detection is disabled when you use -stream.
  • -fix FILESYSTEM — fix a FILESYSTEM that was generated using the -stream option. the cleanup era 🧚
  • -nopad — don't pad the filesystem to a multiple of 4K. no cap.
  • -offset OFFSET — skip OFFSET bytes at the beginning of FILESYSTEM. you can optionally add a K, M or G suffix to say Kbytes, Mbytes or Gbytes respectively. default is 0 bytes.
  • -o OFFSET — a synonym for -offset. same energy, shorter name 💅

🫶 Help options

  • -help — print help summary info to the pager (or stdout if you're not in a terminal).
  • -help-option REGEX — print the help info for options matching REGEX, to the pager (or stdout if not a terminal).
  • -help-section SECTION — print the help info for section SECTION to the pager (or stdout if not a terminal). if SECTION doesn't exactly match a section name, it gets treated as a regular expression and every section name that matches gets displayed. use "list" as the section name to get a list of sections and their names 📋
  • -help-comp COMP — print compressor options for compressor COMP. use "list" to get a list of available compressors, and "all" to get the compressor options for every compressor.
  • -help-all — print help info for all Sqfstar options and sections to the pager (or stdout if not a terminal). the whole buffet 🍓
  • -Xhelp — print compressor options for the selected compressor.
  • -h — shorthand alternative to -help.
  • -ho REGEX — shorthand alternative to -help-option.
  • -hs SECTION — shorthand alternative to -help-section.
  • -ha — shorthand alternative to -help-all.
  • -no-pager — don't use a pager to output help information.
  • -cols WIDTH — use WIDTH columns to output help information. super handy when your output isn't going to a terminal ✨

🌈 Miscellaneous options

  • -fstime TIME — alternative name for mkfs-time.
  • -root-owned — alternative name for -all-root.
  • -noInodeCompression — alternative name for -noI.
  • -noIdTableCompression — alternative name for -noId.
  • -noDataCompression — alternative name for -noD.
  • -noFragmentCompression — alternative name for -noF.
  • -noXattrCompression — alternative name for -noX.

🎀 PSEUDO FILE DEFINITION FORMAT 🎀

okay so this is the part where -p does the heavy lifting. every line starts with a filename and a lil single-letter code that says what to make. here's the whole lineup, no skips:

  • -p "filename d mode uid gid" — create a directory.
  • -p "filename m mode uid gid" — modify filename.
  • -p "filename b mode uid gid major minor" — create a block device.
  • -p "filename c mode uid gid major minor" — create a character device.
  • -p "filename f mode uid gid command" — create file from stdout of command.
  • -p "filename s mode uid gid symlink" — create a symbolic link.
  • -p "filename i mode uid gid [s|f]" — create a socket (s) or FIFO (f).
  • -p "filename x name=val" — create an extended attribute.
  • -p "filename h linkname" — create a hard-link to linkname, follows symlinks.
  • -p "filename l linkname" — create a hard-link to linkname.
  • -p "filename L pseudo_filename" — same, but link to pseudo file.
  • -p "filename D time mode uid gid" — create a directory with timestamp time.
  • -p "filename M time mode uid gid" — modify a file with timestamp time.
  • -p "filename B time mode uid gid major minor" — create block device with timestamp time.
  • -p "filename C time mode uid gid major minor" — create char device with timestamp time.
  • -p "filename F time mode uid gid command" — create file with timestamp time.
  • -p "filename S time mode uid gid symlink" — create symlink with timestamp time.
  • -p "filename I time mode uid gid [s|f]" — create socket/fifo with timestamp time.

💜 SYMBOLIC MODE SPECIFICATION 💜

the symbolic mode has the format [ugoa]*[[+-=]PERMS]+. and PERMS = [rwxXst]+ or [ugo], and the whole sequence can be repeated, separated with commas. slay.

a combo of the letters ugo and a says which permission bits get affected — u means user, g means group, o means other, and a means all, i.e. ugo.

next letter is +, - or =. + means add to the existing permission bits, - means remove those bits from the existing permission bits, and = means set the permission bits. periodt.

the permission bits (PERMS) are a combination of [rwxXst] that sets/adds/removes those bits for the specified ugoa combination — r means read, w means write, and x means execute for files or search for directories. X is the special one ✨: if the file is a directory it's equivalent to x, i.e. search, but if it's a non-directory it only kicks in if execute is already set for user, group or other. the s flag sets user or group ID on execution, and the t flag on a directory sets restricted deletion, or historically made the file sticky if it's a non-directory.

the permission bits can also be u, g or o, which takes the permission bits from the user, group or other of the file respectively. iykyk 💅

⭐ EXIT STATUS ⭐

  • 0 — Sqfstar successfully generated a filesystem. we love to see it 🎉
  • 1 — fatal errors occurred, Sqfstar aborted and did not generate a filesystem. 😭

🦋 COMPRESSORS AVAILABLE AND COMPRESSOR SPECIFIC OPTIONS 🦋

gzip (default):

  • -Xcompression-level COMPRESSION-LEVEL — COMPRESSION-LEVEL should be 1 .. 9 (default 9).
  • -Xwindow-size WINDOW-SIZE — WINDOW-SIZE should be 8 .. 15 (default 15).
  • -Xstrategy strategy1,strategy2,...,strategyN — compress using strategy1,strategy2,...,strategyN in turn and choose the best compression. available strategies: default, filtered, huffman_only, run_length_encoded and fixed.

lzo:

  • -Xalgorithm ALGORITHM — where ALGORITHM is one of: lzo1x_1, lzo1x_1_11, lzo1x_1_12, lzo1x_1_15, lzo1x_999 (default).
  • -Xcompression-level COMPRESSION-LEVEL — COMPRESSION-LEVEL should be 1 .. 9 (default 8). only applies to the lzo1x_999 algorithm.

lz4:

  • -Xhc — compress using LZ4 High Compression. highkey the upgrade 🔥

xz:

  • -Xbcj filter1,filter2,...,filterN — compress using filter1,filter2,...,filterN in turn (in addition to no filter), and choose the best compression. available filters: x86, arm, armthumb, arm64, powerpc, sparc, ia64, riscv.
  • -Xdict-size DICT-SIZE — use DICT-SIZE as the XZ dictionary size. you can give the dictionary size as a percentage of the block size, or as an absolute value. the dictionary size must be less than or equal to the block size and 8192 bytes or larger. it also has to be storable in the xz header as either 2^n or as 2^n+2^(n+1). example dict-sizes are 75%, 50%, 37.5%, 25%, or 32K, 16K, 8K etc.

zstd:

  • -Xcompression-level COMPRESSION-LEVEL — COMPRESSION-LEVEL should be -131072 .. -1 or 1 .. 22 (default 15). negative compression levels correspond to the zstd --fast option. yes the negatives are real and yes they're valid 🙈

lzma:

(no options) (deprecated - no kernel support)

deprecated bestie, and there's no kernel support. just don't ✋

🌸 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 Sqfstar. each command line argument gets wrapped in quotes so there's no ambiguity when arguments contain spaces. and if the file already exists, then the command line is appended to the file.
  • SOURCE_DATE_EPOCH — if set, this is used as the filesystem creation timestamp. also, any file timestamps that are after SOURCE_DATE_EPOCH get clamped to SOURCE_DATE_EPOCH. for more info, see https://reproducible-builds.org/docs/source-date-epoch/.
  • 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 ✨

Bestie, this is the fun part — real commands you can just run. Copy, paste, ascend. 👑

🎀 The basics

sqfstar IMAGE.SQFS < archive.tar

Create a Squashfs filesystem from the uncompressed tar file archive.tar. Sqfstar will use the default compressor (normally gzip), and block size of 128 Kbytes.

sqfstar IMAGE.SQFS < archive.tar

zcat archive.tgz | sqfstar IMAGE.SQFS

Create a Squashfs filesystem from the compressed tar file archive.tgz. Sqfstar will use the default compressor (normally gzip), and block size of 128 Kbytes.

zcat archive.tgz | sqfstar IMAGE.SQFS

sqfstar -b 1M -comp zstd IMAGE.SQFS < archive.tar

Use a block size of 1 Mbyte and Zstandard compression to create the filesystem.

sqfstar -b 1M -comp zstd IMAGE.SQFS < archive.tar

sqfstar -root-uid 0 -root-gid 0 IMAGE.SQFS < archive.tar

Tar files do not supply a definition for the root directory, and the default is to make the directory owned/group owned by the user running Sqfstar. The above command sets the ownership/group ownership to root.

sqfstar -root-uid 0 -root-gid 0 IMAGE.SQFS < archive.tar

sqfstar -root-mode 0755 IMAGE.SQFS < archive.tar

The default permissions for the root directory is 0777 (rwxrwxrwx). The above command sets the permissions to 0755 (rwxr-xr-x).

sqfstar -root-mode 0755 IMAGE.SQFS < archive.tar

sqfstar -all-time now IMAGE.SQFS < archive.tar

Set all file and directory timestamps to "now" (current time) in the filesystem.

sqfstar -all-time now IMAGE.SQFS < archive.tar

sqfstar -force-uid phillip -force-gid phillip IMAGE.SQFS < archive.tar

Make all files and directories in the filesystem owned by "phillip".

sqfstar -force-uid phillip -force-gid phillip IMAGE.SQFS < archive.tar

sqfstar -force-file-mode ugo+r,go-w IMAGE.SQFS < archive.tar

Make all files readable by everyone, but only writable by user, all other permission bits are unaffected.

sqfstar -force-file-mode ugo+r,go-w IMAGE.SQFS < archive.tar

sqfstar IMAGE.SQFS file1 file2 < archive.tar

Exclude file1 and file2 from the tar file when creating filesystem.

sqfstar IMAGE.SQFS file1 file2 < archive.tar

sqfstar IMAGE.SQFS "*.gz" < archive.tar

Exclude any files in the top level directory which matches the wildcard pattern "*.gz".

sqfstar IMAGE.SQFS "*.gz" < archive.tar

sqfstar IMAGE.SQFS "... *.gz" < archive.tar

Exclude any file which matches the wildcard pattern "*.gz" anywhere within the tar file. The initial "..." indicates the wildcard pattern is "non-anchored" and will match anywhere.

sqfstar IMAGE.SQFS "... *.gz" < archive.tar
💀 Note: when passing wildcarded names to Sqfstar, they should be quoted (as in the above examples), to ensure that they are not processed by the shell. The shell will absolutely eat your wildcards alive otherwise, and then you'll be sad. 😭

🦋 Using pseudo file definitions

sqfstar -p "build_dir d 0644 0 0" IMAGE.SQFS < archive.tar

Create a directory called "build_dir" in the output filesystem.

sqfstar -p "build_dir d 0644 0 0" IMAGE.SQFS < archive.tar

sqfstar -p "version.txt l /tmp/build/version" IMAGE.SQFS < archive.tar

Create a reference called "version.txt" to a file not in the tar archive, which acts as if that file was in the tar archive.

sqfstar -p "version.txt l /tmp/build/version" IMAGE.SQFS < archive.tar

sqfstar -p "date.txt f 0644 0 0 date" IMAGE.SQFS < archive.tar

Create a file called "date.txt" which holds the output (stdout) from running the "date" command.

sqfstar -p "date.txt f 0644 0 0 date" IMAGE.SQFS < archive.tar

sqfstar -p "\"hello world\" f 0644 0 0 date" IMAGE.SQFS < archive.tar

As above, but, showing that filenames can have spaces, if they are quoted. The quotes need to be blackslashed to protect them from the shell.

sqfstar -p "\"hello world\" f 0644 0 0 date" IMAGE.SQFS < archive.tar

sqfstar -p "input f 0644 root root dd if=/dev/sda1 bs=1024" IMAGE.SQFS < archive.tar

Create a file containing the contents of partition /dev/sda1". The above allows input from these special files to be captured and placed in the Squashfs filesystem.

sqfstar -p "input f 0644 root root dd if=/dev/sda1 bs=1024" IMAGE.SQFS < archive.tar
🙈 Note: pseudo file definitions should be quoted (as in the above examples), to ensure that they are passed to Mksquashfs as a single argument, and to ensure that they are not processed by the shell. Quote it or lose it, bestie. 💅

💜 AUTHOR 💜

Written by Phillip Lougher <phillip@squashfs.org.uk> — the icon, the moment, the legend. 👑

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.

🌈 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 Sqfstar usage guide can be read here https://github.com/plougher/squashfs-tools/blob/master/Documentation/4.7.5/USAGE-SQFSTAR.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 one's sqfstar version 4.7.5, dated March 2026 — go make some iconic filesystems ✨💖🎀

📦 where this page comes from