1LZ4 - Extremely fast compression
2================================
3
4LZ4 is lossless compression algorithm,
5providing compression speed > 500 MB/s per core,
6scalable with multi-cores CPU.
7It features an extremely fast decoder,
8with speed in multiple GB/s per core,
9typically reaching RAM speed limits on multi-core systems.
10
11Speed can be tuned dynamically, selecting an "acceleration" factor
12which trades compression ratio for faster speed.
13On the other end, a high compression derivative, LZ4_HC, is also provided,
14trading CPU time for improved compression ratio.
15All versions feature the same decompression speed.
16
17LZ4 is also compatible with [dictionary compression](https://github.com/facebook/zstd#the-case-for-small-data-compression),
18both at [API](https://github.com/lz4/lz4/blob/v1.8.3/lib/lz4frame.h#L481) and [CLI](https://github.com/lz4/lz4/blob/v1.8.3/programs/lz4.1.md#operation-modifiers) levels.
19It can ingest any input file as dictionary, though only the final 64KB are used.
20This capability can be combined with the [Zstandard Dictionary Builder](https://github.com/facebook/zstd/blob/v1.3.5/programs/zstd.1.md#dictionary-builder),
21in order to drastically improve compression performance on small files.
22
23
24LZ4 library is provided as open-source software using BSD 2-Clause license.
25
26
27|Branch      |Status   |
28|------------|---------|
29|dev         | [![Build Status][travisDevBadge]][travisLink]    [![Build status][AppveyorDevBadge]][AppveyorLink]                                         |
30
31[travisDevBadge]: https://travis-ci.org/lz4/lz4.svg?branch=dev "Continuous Integration test suite"
32[travisLink]: https://travis-ci.org/lz4/lz4
33[AppveyorDevBadge]: https://ci.appveyor.com/api/projects/status/github/lz4/lz4?branch=dev&svg=true "Windows test suite"
34[AppveyorLink]: https://ci.appveyor.com/project/YannCollet/lz4-1lndh
35
36
37Benchmarks
38-------------------------
39
40The benchmark uses [lzbench], from @inikep
41compiled with GCC v8.2.0 on Linux 64-bits (Ubuntu 4.18.0-17).
42The reference system uses a Core i7-9700K CPU @ 4.9GHz (w/ turbo boost).
43Benchmark evaluates the compression of reference [Silesia Corpus]
44in single-thread mode.
45
46[lzbench]: https://github.com/inikep/lzbench
47[Silesia Corpus]: http://sun.aei.polsl.pl/~sdeor/index.php?page=silesia
48
49|  Compressor             | Ratio   | Compression | Decompression |
50|  ----------             | -----   | ----------- | ------------- |
51|  memcpy                 |  1.000  | 13700 MB/s  |  13700 MB/s   |
52|**LZ4 default (v1.9.0)** |**2.101**| **780 MB/s**| **4970 MB/s** |
53|  LZO 2.09               |  2.108  |   670 MB/s  |    860 MB/s   |
54|  QuickLZ 1.5.0          |  2.238  |   575 MB/s  |    780 MB/s   |
55|  Snappy 1.1.4           |  2.091  |   565 MB/s  |   1950 MB/s   |
56| [Zstandard] 1.4.0 -1    |  2.883  |   515 MB/s  |   1380 MB/s   |
57|  LZF v3.6               |  2.073  |   415 MB/s  |    910 MB/s   |
58| [zlib] deflate 1.2.11 -1|  2.730  |   100 MB/s  |    415 MB/s   |
59|**LZ4 HC -9 (v1.9.0)**   |**2.721**|    41 MB/s  | **4900 MB/s** |
60| [zlib] deflate 1.2.11 -6|  3.099  |    36 MB/s  |    445 MB/s   |
61
62[zlib]: http://www.zlib.net/
63[Zstandard]: http://www.zstd.net/
64
65LZ4 is also compatible and optimized for x32 mode,
66for which it provides additional speed performance.
67
68
69Installation
70-------------------------
71
72```
73make
74make install     # this command may require root permissions
75```
76
77LZ4's `Makefile` supports standard [Makefile conventions],
78including [staged installs], [redirection], or [command redefinition].
79It is compatible with parallel builds (`-j#`).
80
81[Makefile conventions]: https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html
82[staged installs]: https://www.gnu.org/prep/standards/html_node/DESTDIR.html
83[redirection]: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html
84[command redefinition]: https://www.gnu.org/prep/standards/html_node/Utilities-in-Makefiles.html
85
86Building LZ4 - Using vcpkg
87
88You can download and install LZ4 using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
89
90    git clone https://github.com/Microsoft/vcpkg.git
91    cd vcpkg
92    ./bootstrap-vcpkg.sh
93    ./vcpkg integrate install
94    vcpkg install lz4
95
96The LZ4 port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
97
98Documentation
99-------------------------
100
101The raw LZ4 block compression format is detailed within [lz4_Block_format].
102
103Arbitrarily long files or data streams are compressed using multiple blocks,
104for streaming requirements. These blocks are organized into a frame,
105defined into [lz4_Frame_format].
106Interoperable versions of LZ4 must also respect the frame format.
107
108[lz4_Block_format]: doc/lz4_Block_format.md
109[lz4_Frame_format]: doc/lz4_Frame_format.md
110
111
112Other source versions
113-------------------------
114
115Beyond the C reference source,
116many contributors have created versions of lz4 in multiple languages
117(Java, C#, Python, Perl, Ruby, etc.).
118A list of known source ports is maintained on the [LZ4 Homepage].
119
120[LZ4 Homepage]: http://www.lz4.org
121