blob: 980f1d02cb198b9d75dfe507e42ef78f10e2f02e [file] [log] [blame]
erofs-utils includes user-space tools for erofs filesystem.
Currently only mkfs.erofs is available.
It can generate 2 primary kinds of erofs images: (un)compressed.
- For uncompressed images, there will be none of compression
files in these images. However, it can decide whether the tail
block of a file should be inlined or not properly [1].
- For compressed images, it will try to use lz4(hc) algorithm
first for each regular file and see if storage space can be
saved with compression. If not, fallback to an uncompressed
lz4-1.8.0+ for lz4 enabled [2], lz4-1.9.3+ highly recommended [4].
How to build for lz4-1.9.0 or above
To build, you can run the following commands in order:
$ ./
$ ./configure
$ make
mkfs.erofs binary will be generated under mkfs folder.
* For lz4 < 1.9.2, there are some stability issues about
LZ4_compress_destSize(). (lz4hc isn't impacted) [3].
How to build for lz4-1.8.0~1.8.3
For these old lz4 versions, lz4hc algorithm cannot be supported
without lz4-static installed due to LZ4_compress_HC_destSize()
unstable api usage, which means lz4 will only be available if
lz4-static isn't found.
On Fedora, lz4-static can be installed by using:
yum install lz4-static.x86_64
However, it's still not recommended using those versions directly
since there are serious bugs in these compressors, see [2] [3] [4]
as well.
How to generate erofs images
Currently lz4 and lz4hc are available for compression, e.g.
$ mkfs.erofs -zlz4hc foo.erofs.img foo/
Or leave all files uncompressed as an option:
$ mkfs.erofs foo.erofs.img foo/
How to generate legacy erofs images
Decompression inplace and compacted indexes have been introduced in
linux-5.3, which are not forward-compatible with older kernels.
In order to generate _legacy_ erofs images for old kernels,
consider adding "-E legacy-compress" to the command line, e.g.
$ mkfs.erofs -E legacy-compress -zlz4hc foo.erofs.img foo/
Obsoleted erofs.mkfs
There is an original erofs.mkfs version developed by Li Guifu,
which was replaced by the new erofs-utils implementation.
git:// -b obsoleted_mkfs
PLEASE NOTE: This version is highly _NOT recommended_ now.
erofs-utils is under GPLv2+ as a part of erofs project,
feel free to send patches or feedback to us.
linux-erofs mailing list <>
Li Guifu <>
Miao Xie <>
Fang Wei <>
Gao Xiang <>
Chao Yu <>
[1] According to the erofs on-disk format, the tail block of files
could be inlined aggressively with its metadata in order to reduce
the I/O overhead and save the storage space (called tail-packing).
[2] There was a bug until lz4-1.8.3, which can crash erofs-utils
randomly. Fortunately bugfix by our colleague Qiuyang Sun was
merged in lz4-1.9.0.
For more details, please refer to
[3] There were many bugfixes merged into lz4-1.9.2 for
LZ4_compress_destSize(), and I once ran into some crashs due to
those issues. * Again lz4hc is not affected. *
[LZ4_compress_destSize] Allow 2 more bytes of match length
[LZ4_compress_destSize] Fix rare data corruption bug
[LZ4_compress_destSize] Fix overflow condition
[LZ4_compress_destSize] Fix off-by-one error in fix
[LZ4_compress_destSize] Fix off-by-one error
since upstream lz4 doesn't have stable branch for old versions, it's
preferred to use latest upstream lz4 library (although some regressions
could happen since new features are also introduced to latest upstream
version as well) or backport all stable bugfixes to old stable versions,
e.g. our unofficial lz4 fork:
[4] LZ4HC didn't compress long zeroed buffer properly with
which has been resolved in
and already included in lz4-1.9.3, see: