MKSQUASHFS(1) User Commands MKSQUASHFS(1)
NAME
mksquashfs - tool to create and append to squashfs filesystems
SYNOPSIS
mksquashfs source1 source2 ... FILESYSTEM [OPTIONS] [-e list of ex-
clude dirs/files]
DESCRIPTION
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. 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 (default block size 128K).
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 con-
strained block device/memory systems (e.g. embedded systems) where low
overhead is needed.
OPTIONS
Filesystem compression options:
-b BLOCK_SIZE
set data block to BLOCK_SIZE. Default 128 Kbytes. Optionally a
suffix of K or M can be given to specify Kbytes or Mbytes re-
spectively.
-comp COMP
select COMP compression. 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:
-tar read uncompressed tar file from standard in (stdin).
-no-strip
act like tar, and do not strip leading directories from source
files.
-tarstyle
alternative name for -no-strip.
-cpiostyle
act like cpio, and read file pathnames from standard in (stdin).
-cpiostyle0
like -cpiostyle, but filenames are null terminated. Can be used
with find -print0 action.
-reproducible
build filesystems that are reproducible (default).
-not-reproducible
build filesystems that are not reproducible.
-mkfs-time TIME
set filesystem creation timestamp to TIME. TIME can be an un-
signed 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 recog-
nises can be used such as "now", "last week", or "Wed Feb 15
21:02:39 GMT 2023".
-all-time TIME
set all file timestamps to TIME. 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".
-root-time TIME
set root directory time to TIME. 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".
-root-mode MODE
set root directory permissions to octal MODE.
-root-uid VALUE
set root directory owner to specified VALUE, VALUE can be either
an integer uid or user name.
-root-gid VALUE
set root directory group to specified VALUE, VALUE can be either
an integer gid or group name.
-all-root
make all files owned by root.
-force-uid VALUE
set all file uids to specified VALUE, VALUE can be either an in-
teger uid or user name.
-force-gid VALUE
set all file gids to specified VALUE, VALUE can be either an in-
teger gid or group name.
-pseudo-override
make pseudo file uids and gids override -all-root, -force-uid
and -force-gid options.
-no-exports
do not make filesystem exportable via NFS (-tar default).
-exports
make filesystem exportable via NFS (default).
-no-sparse
do not detect sparse files.
-no-tailends
do not pack tail ends into fragments (default).
-tailends
pack tail ends into fragments.
-no-fragments
do not use fragments.
-no-duplicates
do not perform duplicate checking.
-no-hardlinks
do not hardlink files, instead store duplicates.
-keep-as-directory
if one source directory is specified, create a root directory
containing that directory, rather than the contents of the di-
rectory.
Filesystem filter options:
-p PSEUDO-DEFINITION
add pseudo file definition. The definition should be quoted.
-pf PSEUDO-FILE
add list of pseudo file definitions from PSEUDO-FILE, use - for
stdin. Pseudo file definitions should not be quoted.
-sort SORT_FILE
sort files according to priorities in SORT_FILE. One file or
dir with priority per line. Priority -32768 to 32767, default
priority 0.
-ef EXCLUDE_FILE
list of exclude dirs/files. One per line.
-wildcards
allow extended shell wildcards (globbing) to be used in exclude
dirs/files.
-regex allow POSIX regular expressions to be used in exclude
dirs/files.
-max-depth LEVELS
descend at most LEVELS of directories when scanning filesystem.
-one-file-system
do not cross filesystem boundaries. If a directory crosses the
boundary, create an empty directory for each mount point. If a
file crosses the boundary ignore it.
-one-file-system-x
do not cross filesystem boundaries. Like -one-file-system option
except directories are also ignored if they cross the boundary.
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 regu-
lar 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 regu-
lar 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 en-
coded, or prefixed with 0x, where val will be treated as hex-
idecimal. 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.
Mksquashfs runtime options:
-version
print version, licence and copyright message.
-exit-on-error
treat normally ignored errors as fatal.
-quiet no verbose output.
-info print files written to filesystem.
-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 Mksquashfs.
-limit PERCENTAGE
limit the I/O input rate to the given percentage. This can be
used to reduce the I/O and CPU consumption of Mksquashfs (alter-
native to -throttle).
-processors NUMBER
use NUMBER processors. By default will use number of processors
available.
-mem SIZE
use SIZE physical memory for caches. Use K, M or G to specify
Kbytes, Mbytes or Gbytes respectively.
-mem-percent PERCENT
use PERCENT physical memory for caches. Default 25%.
-mem-default
print default memory usage in Mbytes.
Filesystem append options:
-noappend
do not append to existing filesystem.
-root-becomes NAME
when appending source files/directories, make the original root
become a subdirectory in the new root called NAME, rather than
adding the new source items to the original root.
-no-recovery
do not generate a recovery file.
-recovery-path NAME
use NAME as the directory to store the recovery file.
-recover NAME
recover filesystem data using recovery file NAME.
Filesystem actions options:
-action ACTION@EXPRESSION
evaluate EXPRESSION on every file, and execute ACTION if it re-
turns TRUE.
-log-action ACTION@EXPRESSION
as above, but log expression evaluation results and actions per-
formed.
-true-action ACTION@EXPRESSION
as above, but only log expressions which return TRUE.
-false-action ACTION@EXPRESSION
as above, but only log expressions which return FALSE.
-action-file FILE
as action, but read actions from FILE.
-log-action-file FILE
as -log-action, but read actions from FILE.
-true-action-file FILE
as -true-action, but read actions from FILE.
-false-action-file FILE
as -false-action, but read actions from FILE.
Tar file only options:
-default-mode MODE
tar files often do not store permissions for intermediate direc-
tories. This option sets the default directory permissions to
octal MODE, rather than 0755. This also sets the root inode
mode.
-default-uid UID
tar files often do not store uids for intermediate directories.
This option sets the default directory owner to UID, rather than
the user running Mksquashfs. This also sets the root inode uid.
-default-gid GID
tar files often do not store gids for intermediate directories.
This option sets the default directory group to GID, rather than
the group of the user running Mksquashfs. This also sets the
root inode gid.
-ignore-zeros
allow tar files to be concatenated together and fed to Mk-
squashfs. Normally a tarfile has two consecutive 512 byte
blocks filled with zeros which means EOF and Mksquashfs will
stop reading after the first tar file on encountering them. This
option makes Mksquashfs ignore the zero filled blocks.
Expert options (these may make the filesystem unmountable):
-nopad do not pad filesystem to a multiple of 4K.
-offset OFFSET
skip OFFSET bytes at the beginning of FILESYSTEM. Optionally a
suffix of K, M or G can be given to specify Kbytes, Mbytes or
Gbytes respectively. Default 0 bytes.
-o OFFSET
synonym for -offset.
Miscellaneous options:
-fstime TIME
alternative name for -mkfs-time.
-always-use-fragments
alternative name for -tailends.
-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.
-help output this options text to stdout.
-h output this options text to stdout.
-Xhelp print compressor options for selected compressor.
PSEUDO FILE DEFINITION FORMAT
-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 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.
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, fil-
tered, 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
lzo1x_999 algorithm.
lz4:
-Xhc Compress using LZ4 High Compression.
xz:
-Xbcj filter1,filter2,...,filterN
Compress using filter1,filter2,...,filterN in turn (in addition
to no filter), and choose the best compression. Available fil-
ters: x86, arm, armthumb, powerpc, sparc, ia64.
-Xdict-size DICT-SIZE
Use DICT-SIZE as the XZ dictionary size. The dictionary size
can be specified as a percentage of the block size, or as an ab-
solute value. The dictionary size must be less than or equal to
the block size and 8192 bytes or larger. It must also be stor-
able 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 1 .. 22 (default 15).
lzma:
(no options) (deprecated - no kernel support)
ENVIRONMENT
SOURCE_DATE_EPOCH
If set, this is used as the filesystem creation timestamp. Also
any file timestamps which are after SOURCE_DATE_EPOCH will be
clamped to SOURCE_DATE_EPOCH. See https://repro-
ducible-builds.org/docs/source-date-epoch/ for more information.
EXAMPLES
mksquashfs DIRECTORY IMAGE.SQFS
Create a Squashfs filesystem from the contents of DIRECTORY,
writing the output to IMAGE.SQSH. Mksquashfs will use the de-
fault compressor (normally gzip), and block size of 128 Kbytes.
mksquashfs DIRECTORY FILE1 FILE2 IMAGE.SQFS
Create a Squashfs filesystem containing DIRECTORY and FILE1 and
FILE2. If multiple sources are specified on the command line
they will be combined into a single directory.
mksquashfs DIRECTORY IMAGE.SQFS -b 1M -comp zstd
Use a block size of 1 Mbyte and Zstandard compression to create
the filesystem.
mksquashfs DIRECTORY IMAGE.SQFS -e file1 file2
Exclude file1 and file2 from DIRECTORY when creating filesystem.
No wildcard matching of files.
mksquashfs DIRECTORY IMAGE.SQFS -wildcards -e "*.gz"
Exclude anything in DIRECTORY which matches the wildcard pattern
"*.gz".
mksquashfs DIRECTORY IMAGE.SQFS -wildcards -e "... *.gz"
Exclude files which match the wildcard pattern "*.gz" anywhere
within DIRECTORY and its sub-directories. The initial "..." in-
dicates the wildcard pattern is "non-anchored" and will match
anywhere.
Note: when passing wildcarded names to Mksquashfs, they should be
quoted (as in the above examples), to ensure that they are not
processed by the shell.
Using pseudo file definitions
mksquashfs DIRECTORY IMAGE.SQFS -p "build_dir d 0644 0 0"
Create a directory called "build_dir" in the output filesystem.
mksquashfs DIRECTORY IMAGE.SQFS -p "version.txt l /tmp/build/version"
Create a reference called "version.txt" to a file outside DIREC-
TORY, which acts as if the file "/tmp/build/version" was copied
or hard-linked into DIRECTORY before calling Mksquashfs.
mksquashfs DIRECTORY IMAGE.SQFS -p "date.txt f 0644 0 0 date"
Create a file called "date.txt" which holds the output (stdout)
from running the "date" command.
mksquashfs DIRECTORY IMAGE.SQFS -p "\"hello world\" f 0644 0 0 date"
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.
mksquashfs - IMAGE.SQFS -p "input f 0644 root root dd if=/dev/sda1
bs=1024" -p "/ d 0644 0 0"
Create a file containing the contents of partition /dev/sda1".
Ordinarily Mksquashfs given a device, fifo, or named socket will
place that special file within the Squashfs filesystem, the
above allows input from these special files to be captured and
placed in the Squashfs filesystem. Note there are no other
sources than the pseudo file, and so the command line source is
"-". If there are no other sources than pseudo files, the root
(/) directory must be defined too, as seen in this example.
unsquashfs -pf - IMAGE.SQFS | mksquashfs - NEW.SQFS -pf -
Transcode IMAGE.SQFS to NEW.SQFS by piping the pseudo file out-
put from Unsquashfs to Mksquashfs using stdout and stdin. This
can convert from earlier Squashfs filesystems or change compres-
sion algorithm, block size etc. without needing to unpack into
an intermediate directory or file.
Note: pseudo file definitions should be quoted (as in the above exam-
ples), to ensure that they are passed to Mksquashfs as a single argu-
ment, and to ensure that they are not processed by the shell.
Using extended attribute options
mksquashfs DIRECTORY IMAGE.SQFS -no-xattrs
Do not store any extended attributes in the Squashfs filesystem.
Any extended attributes in the source files will be ignored.
mksquashfs DIRECTORY IMAGE.SQFS -xattrs-include "^user."
Filter the extended attributes in the source files, and only
store extended attributes in the user namespace in the Squashfs
filesystem.
mksquashfs DIRECTORY IMAGE.SQFS -xattrs-exclude "^user."
Filter the extended attributes in the source files, and don't
store any extended attributes in the user namespace in the
Squashfs filesystem.
mksquashfs DIRECTORY IMAGE.SQFS -xattrs-add "user.comment=hello world"
Add the extended attribute called "user.comment" with the con-
tent "hello world" to all files and directories in the Squashfs
filesystem.
mksquashfs DIRECTORY IMAGE.SQFS -xattrs-add "user.comment=0thello
world\012"
Add the extended attribute called "user.comment" to all files
and directories, but in this case the contents of the extended
attribute will be "hello world" with a trailing newline charac-
ter (012 octal).
mksquashfs DIRECTORY IMAGE.SQFS -xattrs-add "user.com-
ment=0saGVsbG8gd29ybGQ="
Add the extended attribute called "user.comment" to all files
and directories, where the value is given in base64 encoding,
representing "hello world".
mksquashfs DIRECTORY IMAGE.SQFS -action "-xattrs-include(^user.) @
type(f)"
Filter the extended attributes but only in regular files (type
f), and only store extended attributes in the user namespace.
mksquashfs DIRECTORY IMAGE.SQFS -p "hello_world x user.comment=0tsalve
mundi\012"
Add the extended attribute called "user.comment" to the file
called "hello_world", with the contents of the extended at-
tribute being "salve mundi" with a trailing newline character
(012 octal).
Using Actions to not compress, change attributes etc.
mksquashfs DIRECTORY IMAGE.SQSH -action "uncompressed @ (name(*.jpg) ||
name(*.mpg) ) || (name(*.img) && filesize(+1G))"
Specify that any files matching the wildcards "*.jpg" and
"*.mpg" should not be compressed. Additionally, it also speci-
fies any files matching the wildcard "*.img" and are larger than
1 Gigabyte should be uncompressed too. This shows test opera-
tors can be combined with logical expressions.
mksquashfs DIRECTORY IMAGE.SQSH -action "chmod(o+r)@! perm(o+r)"
If any files within DIRECTORY are not readable by "others", then
make them readable by others in the Squashfs filesystem.
mksquashfs DIRECTORY IMAGE.SQSH -action "uid(phillip)@! perm(o+r)"
As previous, match on any files which are not readable by "oth-
ers", but, in this case change the owner of the file to
"phillip" in the Squashfs filesystem.
mksquashfs DIRECTORY IMAGE.SQSH -action "prune @ type(l) && ! exists"
Delete any symbolic link within DIRECTORY which points outside
of DIRECTORY, i.e. will be unresolvable in the Squashfs filesys-
tem.
mksquashfs DIRECTORY IMAGE.SQSH -action "exclude @ depth(3)"
Create a Squashfs filesystem containing the two top most levels
(contents of DIRECTORY and immediate sub-directories), and ex-
clude anything at level 3 or below.
mksquashfs DIRECTORY IMAGE.SQFS -action "-xattrs-include(^user.) @
type(f)"
Filter the extended attributes but only in regular files (type
f), and only store extended attributes in the user namespace.
Note: actions 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.
AUTHOR
Written by Phillip Lougher <phillip@squashfs.org.uk>
COPYRIGHT
Copyright © 2023 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 MER-
CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.
SEE ALSO
unsquashfs(1), sqfstar(1), sqfscat(1)
The README for the Squashfs-tools 4.6.1 release, describing the new
features can be read here
https://github.com/plougher/squashfs-tools/blob/master/README-4.6.1
The Squashfs-tools USAGE guide can be read here
https://github.com/plougher/squashfs-tools/blob/master/USAGE-4.6
The ACTIONS-README file describing how to use the new actions feature
can be read here https://github.com/plougher/squashfs-tools/blob/mas-
ter/ACTIONS-README
mksquashfs version 4.6.1 April 2024 MKSQUASHFS(1)
Generated by dwww version 1.16 on Tue Dec 16 15:03:17 CET 2025.