From LinuxReviews
Jump to navigationJump to search
data.c EROFS source file
data.c EROFS source file
  • Li Guifu
  • Miao Xie
  • Fang Wei
  • Gao Xiang (高翔)
  • Chao Yu
Full nameEnhanced Read-Only File System
Introduced2018; 3 years ago (2018)
Repositorykernel module: fs/erofs
erofs-utils: xiang/erofs-utils.git filesystems/erofs.rst
Max. file size
  • 4 GiB (version 1)
  • 16 EiB (version 2)
Max. number of files
  • 65,536 (version 1)
  • 4,294,967,296 (version 2)
Max. filename length255 bytes
Dates recordedCreate (version 2 only)
Date resolution1 ns
AttributesPOSIX, xattr
File system permissionsPOSIX, ACL
Transparent compressionYes (LZ4)
Supported operating systemsLinux

Enhanced Read-Only File System is a efficient high-performance read only filesystem developed by Gao Xiang. It features in-place decompression for maximum efficiency. EROFS has features which makes it superior to other read-only filesystems like squashfs on devices with limited memory. LZ4 is currently the only supported compression algorithm.

EROFS was first introduced to the Linux kernel's "staging" area in 2018. It became part of the mainline Linux kernel when Linux 5.4 was released in November 2019. The user-space utilities are available in erofs-utils.git.


  • Little-endian on-disk design.
  • 4KB block size. This limits the total possible capacity of a EROFS filesystem to 16 TB.
  • Optional support for extended attributes (xattrs)
  • Supports POSIX.1e ACLs by using xattrs
  • Fixed-output compression for high performance
  • Transparent LZ4 compression. LZ4 is the only supported algorithm.

EROFS supports who different inode versions:

v1 v2
Inode metadata size: 32 bytes 64 bytes
Max file size 4 GB 16 EB (also limited by max. vol size)
Max uids/gids 65536 4294967296
File creation time no yes (64 + 32-bit timestamp)
Max hardlinks 65536 4294967296
Metadata reserved 4 bytes 14 bytes

User-space utilities

Compressed EROFS images can be created with mkfs.erofs which comes as a part fo the erofs-utils package (actually, it's the only binary in that package). The code can be aqcuired from

All the distributions have erofs-utils as of September 2020. It is unlikely that you will need to compile erofs-utils yourself at this time.

erofs-utils requires lz4 and it has issues with lz4 <=1.8.3. You may want to compile both lz4 and erofs-utils from git if your distribution provides a version prior to lz4 <=1.9.0:

git clone
cd lz4/
su -c 'make install'

make install will by default install to /usr/local/ which means lz4's include and library directories need to be specified when compiling erofs-utils:

git clone git:// -b dev
cd erofs-utils/
./configure --with-lz4-incdir=/usr/local/include/ --with-lz4-libdir=/usr/local/lib
su -c 'make install'


The basic syntax for creating a EROFS image is:

mkfs.erofs -zlz4hc myimage.erofs folder1/ folder2/

-z for lz4 required even though it is currently the only supposed compression algorithm.

A mounting EROFS images is done the same way you would mount a ISO image or any other file as a read only file system:

sudo mount -o loop myimage.erofs /mnt/tmp

The kernel ring buffer (dmesg) shows notifications with a erofs image is mounted:

erofs: (device loop2): mounted with root inode @ nid 38.

Mount options

fault_injection=%d Enable fault injection in all supported types with specified injection rate. Supported injection type:
Type_Name Type_Value
FAULT_KMALLOC 0x000000001
FAULT_READ_IO 0x000000002
(no)user_xattr Setup Extended User Attributes. Note: xattr is enabled by default if CONFIG_EROFS_FS_XATTR is selected.
(no)acl Setup POSIX Access Control List. Note: acl is enabled
cache_strategy=%s Select a strategy for cached decompression.

disabled: In-place I/O decompression only;
readahead: Cache the last incomplete compressed physical cluster for further reading. It still does in-place I/O decompression for the rest compressed physical clusters;
readaround: Cache the both ends of incomplete compressed physical clusters for further reading. It still does in-place I/O decompression for the rest compressed physical clusters.

In most cases the standard -o loop option is enough to mount a EROFS image. However, you can use the different options listed above to tweak it:

mount -o loop,cache_strategy=readahead myimage.erofs /mnt/tmp

Technical details

EROFS supports 4KB fixed-output clustersize transparent file compression.

         |---- Variant-Length Extent ----|-------- VLE --------|----- VLE -----
         clusterofs                      clusterofs            clusterofs
         |                               |                     |   logical data
... |    .        |             |        .    |             |  .          | ...
    |-> cluster <-|-> cluster <-|-> cluster <-|-> cluster <-|-> cluster <-|
         size          size          size          size          size
          .                             .                .                   .
           .                       .               .                  .
            .                  .              .                .
         ... |             |             |             | ... physical data
             |-> cluster <-|-> cluster <-|-> cluster <-|
                  size          size          size

A physical cluster can contain a maximum of 4KB compressed or uncompressed data. Logical clusters have a on-disk index which describes it's physical cluster address, cluster type and other details.

Add your comment
LinuxReviews welcomes all comments. If you do not want to be anonymous, register or log in. It is free.