MKFS.EROFS(1)

MKFS.EROFS 💅✨

okay bestie, welcome to the mkfs.erofs manual page 💖 — that's section 1 of the General Commands Manual, iykyk. this is the tool that makes EROFS filesystems, and she is lowkey iconic.

---

NAME 🎀

mkfs.erofs — tool to create an EROFS filesystem

---

SYNOPSIS 🌸

mkfs.erofs [OPTIONS] DESTINATION SOURCE

---

DESCRIPTION 🦋

so EROFS is a new enhanced lightweight linux read-only filesystem with modern designs — we're talking no buffer head, reduced metadata, inline xattrs/data, the whole glow-up — and it exists for scenarios that need high-performance read-only requirements. like, think Android OS on smartphones, and LIVECDs. fr fr.

she also does fixed-sized output compression, which improves storage density and keeps relatively higher compression ratios. that's super useful for getting high performance on embedded devices with limited memory, because it has unnoticable memory overhead and page cache thrashing. no cap. 👑

mkfs.erofs is the one used to create such an EROFS filesystem DESTINATION image file from various SOURCE, where SOURCE can be:

• a local directory
• a (compressed) tarball
• an S3 bucket or a prefix within it
• an OCI image reference
• other EROFS image(s), see REBUILD MODE below

---

OPTIONS ✨

• -b block-size — set the fundamental block size of the filesystem in bytes. in other words: specify the smallest amount of data that can be accessed at a time. default is the system page size. and bestie, it cannot be less than 512 bytes. 🙈
• -C max-pcluster-size — specify the maximum size of compress physical cluster in bytes. heads up, this may cause the big pcluster feature to be enabled (Linux 5.13+). 🔥
• -m #[:compression-algorithm] — enable metadata compression with #-byte clusters in a metabox inode (Linux 6.17+); you can optionally specify a compression algorithm too (it defaults to the data compression algorithm if you omit it).
• --MZ[=<0|[id]>] — put inode metadata ('i') and/or directory data ('d') into the separate metadata zone. this improves spatial locality of metadata layout within the image, which is beneficial for metadata access if the storage has long I/O latencies. very thoughtful of her 💅
• -x # — limit how many xattrs will be inlined. the default is 2.
• -z compression-algorithm[,#][:...] — set a primary algorithm for data compression, which can be set with an optional compression level. alternative algorithms could be specified too, separated by colons. 👀 see the output of mkfs.erofs --help for a listing of the algorithms that mkfs.erofs is compiled with and what their respective level ranges are.
• --zD[=<0|1>] — used to enable directory compression: 0=disable, 1=enable. if the optional argument is omitted, directory compression is enabled by default. slay.
• -d # — specify the level of debugging messages. the default is 2, which shows basic warning messages. and disables storing xattrs if < 0. 🫶
• -E [^]extended-option[,...] — set extended options for the filesystem. extended options are comma separated, and may take an extra argument using the equals ('=') sign. to disable a feature, usually prefix the extended option name with a caret ('^') character. the following extended options are supported:
  • 48bit — enable 48-bit block addressing and encoded extents to support larger filesystem images and byte-oriented data compression mainly for Zstandard. (Linux 6.15+)
  • all-fragments — forcely record the whole files into a special inode for better compression, and it may take an argument as the pcluster size of the packed inode in bytes. (Linux 6.1+)
  • dedupe — enable global compressed data deduplication to minimize duplicated data in the filesystem. may further reduce image size when used with -E fragments. (Linux 6.1+)
  • dot-omitted — omit the "." (dot) directory entry in all directories to reduce metadata overhead (Linux 6.15+). it will also enable 48bit on-disk layout.
  • force-inode-compact — force generation of compact (32-byte) inodes.
  • force-inode-extended — force generation of extended (64-byte) inodes.
  • force-inode-blockmap — force generation of inode chunk format as a 4-byte block address array.
  • force-chunk-indexes — forcely generate inode chunk format as an 8-byte chunk index (with device ID).
  • [^]fragdedupe[=<inode|full>] — set the mode for fragment data deduplication. it's effective only when -E(all)-fragments is used together. if a caret ('^') character is set, fragment data deduplication is disabled.
    • inode — deduplicate fragment data only when the inode data is identical. this option will result in faster image generation with the current codebase
    • full — always deduplicate fragment data if possible
  • fragments[=size] — pack the tail part (pcluster) of compressed files, or entire files, into a special inode for smaller image sizes, and it may take an argument as the pcluster size of the packed inode in bytes. (Linux 6.1+)
  • ^inline_data — don't inline regular files. it's typically useful to enable FSDAX (Linux 5.15+) for those images, however, there could be other use cases too.
  • legacy-compress — (obsolete; should not be used in daily use) disable "compacted indexes" on-disk layout. > bestie do NOT use this in your daily life, it said so itself 😭
  • nosbcrc — disable filesystem superblock checksum explicitly.
  • plain-xattr-prefixes — store long extended attribute name prefixes directly on disk rather than in special inodes. by default, long xattr name prefixes are placed in metabox_inode (if metabox is enabled) or packed_inode (if fragments is enabled). this option forces them to be stored as plain on-disk structures.
  • xattr-name-filter — enable a name filter for extended attributes to optimize negative lookups. (Linux 6.6+).
  • ztailpacking — pack the tail part (pcluster) of compressed files into its metadata to save more space and the tail part I/O. (Linux 5.17+)
• -L volume-label — set the volume label for the filesystem to volume-label. the maximum length of the volume label is 15 bytes.
• -T # — specify a UNIX timestamp for image creation time for reproducible builds. if --mkfs-time is not specified, it will behave as --all-time: setting all files to the specified UNIX timestamp instead of using the modification times of the source files. 🕰️
• -U UUID — set the universally unique identifier (UUID) of the filesystem to UUID. the format of the UUID is a series of hex digits separated by hyphens, like this: "c1b9d5a2-f162-11cf-9ece-0020afc76f16". the UUID parameter may also be one of the following:
  • clear — clear the file system UUID
  • random — generate a new randomly-generated UUID
• --all-root — make all files owned by root. 👑
• --all-time — (used together with -T) set all files to the fixed timestamp. this is the default.
• --async-queue-limit=# — specify the maximum number of entries in the multi-threaded job queue.
• --aufs — replace aufs special files with overlayfs metadata.
• --blobdev file — specify an extra blob device to store chunk-based data.
• --chunksize # — generate chunk-based files with #-byte chunks.
• --clean=MODE — run full clean build with the given MODE, which could be one of data, rvsp, or 0.

if --clean is specified without an explicit value, it is treated as --clean=data.

• data: import complete file data from the source into the destination image, creating a fully self-contained EROFS image. this mode is useful when you need a standalone image that doesn't depend on external blob devices.
• rvsp: reserve space for file data in the destination image without copying the actual content. the file data will need to be filled in later through other means. this is useful for creating sparse images or when the actual data will be populated separately.
• 0: fill all inode data with zeros.

the current source-specific support for MODE:

• Local directory source — only data is supported. rvsp and 0 will be ignored.
• Tar source (--tar) — data and rvsp are supported. 0 will be ignored. note that rvsp takes precedence over --tar=i or --tar=headerball.
• Rebuild mode — data and rvsp are supported.
• S3 source (--s3) — data and 0 are supported.
• OCI source (--oci) — only data is supported.

• --compress-hints= file — apply a per-file compression strategy. each line in file is defined by tokens separated by spaces in the following form. optionally, instead of the given primary algorithm, alternative algorithms can be specified with algorithm-index explicitly:

<pcluster-size-in-bytes> [algorithm-index] <match-pattern>

match-patterns are extended regular expressions, matched against absolute paths within the output filesystem, with no leading /. 💅

• --dsunit=# — align all data block addresses to multiples of #.

if --dsunit and --chunksize are both set, --dsunit will be ignored if it is larger than --chunksize.

if --dsunit is larger, it spans multiple chunks, for example: -b 4096, --dsunit 512 (2MiB), --chunksize 4096

once a chunk is deduplicated, all subsequent chunks will no longer be aligned. for optimal performance, it is recommended to set --dsunit to the same value as --chunksize:

E.g. -b 4096, --dsunit 512 (2MiB), --chunksize $((4096*512))

• --exclude-path=path — skip any file that matches this exact literal path, like, character-for-character. You can pass --exclude-path as many times as you want 💅
• --exclude-regex=regex — skip files matching this extended regular expression. Multiple --exclude-regex options? Absolutely allowed, stack 'em up 🫶
• --file-contexts=file — read your SELinux label config/overrides out of file, in the selinux_file(5) format.
• --force-uid=UID — set every single file's UID to UID. everyone gets the same vibe, no cap.
• --force-gid=GID — same energy, but for GIDs: every file's GID becomes GID.
• --fsalignblks=# — specify the alignment of the primary device size (usually that's the filesystem size) in blocks.
• --gid-offset=GIDOFFSET — add GIDOFFSET to all file GIDs. And when you run this alongside --force-gid, the final file gids land on GID + GID-OFFSET. math is math 🧮
• --gzinfo[=file] — (used together with --tar) generate AWS SOCI-compatible zinfo so you get random gzip access. Heads up bestie: the source file must be a gzip-compressed tarball, or it's not giving.
• --hard-dereference — dereference hardlinks and add each link as a separate inode. They're all main characters now, no shared destiny 💀
• --ignore-mtime — ignore the file modification time whenever it would make mkfs.erofs use extended inodes over compact inodes. When you're not using a fixed timestamp, this can shrink the total metadata size. It's also implied by -E force-inode-compact. tiny image, huge slay.
• --incremental=MODE — run an incremental build, where DESTINATION is an existing EROFS image and the data from SOURCE gets incrementally appended to it. MODE means the same thing it does in --clean above. Also, real talk: incremental build is unsupported for --s3 and --oci sources. 🙈

If you write --incremental with no explicit value, it's treated as --incremental=data.

The current source-specific support for MODE, laid out for you:

• Local directory source — only data is supported. rvsp and 0 will be ignored.
• Tar source (--tar) — data and rvsp are supported. 0 will be ignored. Note that rvsp takes precedence over --tar=i or --tar=headerball.
• Rebuild mode — only rvsp is supported.

• --max-extent-bytes=# — specify the maximum decompressed extent size in bytes. The default is unlimited. go big or go home ✨
• --mkfs-time — (used together with -T) the given timestamp only gets applied to the build time. that's it, that's the whole job.
• --mount-point=path — specify the prefix of the target filesystem path. default: /.
• --oci[=<f|i>] — generate a full (f) or index-only (i) image from an OCI remote source. And you can sprinkle in these extra options too:
  • platform=platform — specify the platform. default: linux/amd64.
  • layer=# — specify the layer index to extract (0-based; omit it and you extract all layers).
  • blob=digest — specify the blob digest to extract (omit it and, again, all layers).
  • username=username — username for authentication (optional).
  • password=password — password for authentication (optional).
  • insecure — use HTTP instead of HTTPS (optional). 🫣
• --offset=# — skip # bytes at the beginning of the image.
• --ovlfs-strip[=<0|1>] — strip overlayfs metadata in the target image (think whiteouts and such).
• --preserve-mtime — use extended inodes instead of compact inodes if the file modification time would overflow compact inodes. This is the default, and it overrides --ignore-mtime. ✨
• --quiet — quiet execution (do not write anything to standard output.) 🤫
• --root-xattr-isize=# — ensure the inline xattr size of the root directory is at least # bytes.
• --s3=endpoint — generate an image from an S3-compatible object store. Extra options you can specify:
  • passwd_file=file — S3FS-compatible password file, with the format of "accessKey:secretKey" in the first line.
  • urlstyle=style — S3 API calling style (vhost or path). default: vhost.
  • sig=version — S3 API signature version (2 or 4). default: 2.
  • region=code — region code in which endpoint belongs to (required for sig=4).
• --sort=MODE — inode data sorting order for tarballs as input.

MODE may be one of none or path.

• none: no particular data order is specified for the target image, to avoid unnecessary overhead; currently, it takes effect if -E^inline_data is specified and no compression is applied.
• path: data order strictly follows the tree generation order. (default)

• --tar, --tar=MODE — treat SOURCE as a tarball, or a tarball-like "headerball", rather than as a directory.

MODE may be one of f, i, or headerball.

• f: generate a full EROFS image from a regular tarball. (default)
• i: generate a meta-only EROFS image from a regular tarball. Only metadata such as dentries, inodes, and xattrs will be added to the image, without file data. Uses for such images include as a layer in an overlay filesystem with other data-only layers. so cute, so lightweight.
• headerball: generate a meta-only EROFS image from a stream identical to a tarball except that file data is not present after each file header.

• --uid-offset=UIDOFFSET — add UIDOFFSET to all file UIDs. When this is used together with --force-uid, the final file uids are set to UID + UIDOFFSET.
• --ungzip[=file] — filter tarball streams through gzip. Optionally, raw streams can be dumped together.
• --unxz[=file] — filter tarball streams through xz, lzma, or lzip. Optionally, raw streams can be dumped together.
• --vmdk-desc=FILE — generate a VMDK descriptor file to merge sub-filesystems, which can be used for tar index or rebuild mode.
• --workers=# — set the number of worker threads to #. default: number of CPUs. get that parallel slay 💅
• --xattr-inode-digest=name — specify the extended attribute name to record inode digests.
• --xattr-prefix=PREFIX — specify a customized extended attribute namespace prefix for space saving, e.g. "trusted.overlay.". You may give multiple --xattr-prefix options (Linux 6.4+). 👑
• --zfeature-bits=# — toggle filesystem compression features according to given bits #. Each bit in the value corresponds to a specific compression feature:

7 6 5 4 3 2 1 0  (bit position)
| | | | | | | |
| | | | | | | +-- Bit 0 (1)   : legacy-compress
| | | | | | +---- Bit 1 (2)   : ztailpacking
| | | | | +------ Bit 2 (4)   : fragments
| | | | +-------- Bit 3 (8)   : all-fragments
| | | +---------- Bit 4 (16)  : dedupe
| | +------------ Bit 5 (32)  : fragdedupe
| +-------------- Bit 6 (64)  : 48bit
+---------------- Bit 7 (128) : dot-omitted

For example, --zfeature-bits=6 (binary: 0000 0110) enables ztailpacking (bit 1) and fragments (bit 2). bit math but make it fashion ✨

• -h, --help — display the help string and exit.
• -V, --version — print the version number and exit.

---

📝 NOTES 📝

🔁 REBUILD MODE 🔁

Rebuild mode lets mkfs.erofs generate a brand new EROFS image from one or more existing EROFS images passed as SOURCE(s). This mode is particularly useful for merging multiple EROFS images, or for creating index-only metadata images that reference data in the source images. it's giving remix era 💖

When SOURCE contains one or more EROFS image files, mkfs.erofs automatically enters rebuild mode. The behavior is controlled by the --clean or --incremental options, which decide how file data gets handled:

• Default mode (blob index) — the generated image contains only metadata (inodes, dentries, and xattrs). File data is referenced through chunk-based indexes pointing to the original source images, which act as external blob devices. This creates a compact metadata layer suitable for layered filesystem scenarios, similar to container image layers. no cap, this is the icon of efficiency.
• data mode — --clean=data: import complete file data from all source images into the destination image, producing a fully self-contained EROFS image that does not depend on external blob devices. it has abandonment issues, in a good way 🫶
• rvsp mode — --clean=rvsp or --incremental=rvsp: reserve space for file data without copying actual content, useful for creating sparse images. manifesting the data, not copying it ✨

---

🎀 AUTHOR 🎀

This version of mkfs.erofs is written by Li Guifu <blucerlee@gmail.com>, Miao Xie <miaoxie@huawei.com> and Gao Xiang <xiang@kernel.org> with continuously improvements from others. legends only 👑

This manual page was written by Gao Xiang <xiang@kernel.org>.

---

🌈 AVAILABILITY 🌈

mkfs.erofs is part of the erofs-utils package and is available from git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git. go clone it bestie 💅

---

👀 SEE ALSO 👀

• mkfs(8).

---

okay that's the whole page, bestie!! 🫶 this is mkfs.erofs(1) from the erofs-utils family — go make some iconic little filesystems, and remember: compact inodes are the vibe, blob indexes are the moment, and -h is always there if you get lost 💖✨🌸