1<p align="center"><img src="https://raw.githubusercontent.com/facebook/zstd/dev/doc/images/zstd_logo86.png" alt="Zstandard"></p> 2 3__Zstandard__, or `zstd` as short version, is a fast lossless compression algorithm, 4targeting real-time compression scenarios at zlib-level and better compression ratios. 5It's backed by a very fast entropy stage, provided by [Huff0 and FSE library](https://github.com/Cyan4973/FiniteStateEntropy). 6 7Zstandard's format is stable and documented in [RFC8878](https://datatracker.ietf.org/doc/html/rfc8878). Multiple independent implementations are already available. 8This repository represents the reference implementation, provided as an open-source dual [BSD](LICENSE) and [GPLv2](COPYING) licensed **C** library, 9and a command line utility producing and decoding `.zst`, `.gz`, `.xz` and `.lz4` files. 10Should your project require another programming language, 11a list of known ports and bindings is provided on [Zstandard homepage](http://www.zstd.net/#other-languages). 12 13**Development branch status:** 14 15[![Build Status][travisDevBadge]][travisLink] 16[![Build status][AppveyorDevBadge]][AppveyorLink] 17[![Build status][CircleDevBadge]][CircleLink] 18[![Build status][CirrusDevBadge]][CirrusLink] 19[![Fuzzing Status][OSSFuzzBadge]][OSSFuzzLink] 20 21[travisDevBadge]: https://api.travis-ci.com/facebook/zstd.svg?branch=dev "Continuous Integration test suite" 22[travisLink]: https://travis-ci.com/facebook/zstd 23[AppveyorDevBadge]: https://ci.appveyor.com/api/projects/status/xt38wbdxjk5mrbem/branch/dev?svg=true "Windows test suite" 24[AppveyorLink]: https://ci.appveyor.com/project/YannCollet/zstd-p0yf0 25[CircleDevBadge]: https://circleci.com/gh/facebook/zstd/tree/dev.svg?style=shield "Short test suite" 26[CircleLink]: https://circleci.com/gh/facebook/zstd 27[CirrusDevBadge]: https://api.cirrus-ci.com/github/facebook/zstd.svg?branch=dev 28[CirrusLink]: https://cirrus-ci.com/github/facebook/zstd 29[OSSFuzzBadge]: https://oss-fuzz-build-logs.storage.googleapis.com/badges/zstd.svg 30[OSSFuzzLink]: https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:zstd 31 32## Benchmarks 33 34For reference, several fast compression algorithms were tested and compared 35on a desktop running Ubuntu 20.04 (`Linux 5.11.0-41-generic`), 36with a Core i7-9700K CPU @ 4.9GHz, 37using [lzbench], an open-source in-memory benchmark by @inikep 38compiled with [gcc] 9.3.0, 39on the [Silesia compression corpus]. 40 41[lzbench]: https://github.com/inikep/lzbench 42[Silesia compression corpus]: http://sun.aei.polsl.pl/~sdeor/index.php?page=silesia 43[gcc]: https://gcc.gnu.org/ 44 45| Compressor name | Ratio | Compression| Decompress.| 46| --------------- | ------| -----------| ---------- | 47| **zstd 1.5.1 -1** | 2.887 | 530 MB/s | 1700 MB/s | 48| [zlib] 1.2.11 -1 | 2.743 | 95 MB/s | 400 MB/s | 49| brotli 1.0.9 -0 | 2.702 | 395 MB/s | 450 MB/s | 50| **zstd 1.5.1 --fast=1** | 2.437 | 600 MB/s | 2150 MB/s | 51| **zstd 1.5.1 --fast=3** | 2.239 | 670 MB/s | 2250 MB/s | 52| quicklz 1.5.0 -1 | 2.238 | 540 MB/s | 760 MB/s | 53| **zstd 1.5.1 --fast=4** | 2.148 | 710 MB/s | 2300 MB/s | 54| lzo1x 2.10 -1 | 2.106 | 660 MB/s | 845 MB/s | 55| [lz4] 1.9.3 | 2.101 | 740 MB/s | 4500 MB/s | 56| lzf 3.6 -1 | 2.077 | 410 MB/s | 830 MB/s | 57| snappy 1.1.9 | 2.073 | 550 MB/s | 1750 MB/s | 58 59[zlib]: http://www.zlib.net/ 60[lz4]: http://www.lz4.org/ 61 62The negative compression levels, specified with `--fast=#`, 63offer faster compression and decompression speed 64at the cost of compression ratio (compared to level 1). 65 66Zstd can also offer stronger compression ratios at the cost of compression speed. 67Speed vs Compression trade-off is configurable by small increments. 68Decompression speed is preserved and remains roughly the same at all settings, 69a property shared by most LZ compression algorithms, such as [zlib] or lzma. 70 71The following tests were run 72on a server running Linux Debian (`Linux version 4.14.0-3-amd64`) 73with a Core i7-6700K CPU @ 4.0GHz, 74using [lzbench], an open-source in-memory benchmark by @inikep 75compiled with [gcc] 7.3.0, 76on the [Silesia compression corpus]. 77 78Compression Speed vs Ratio | Decompression Speed 79---------------------------|-------------------- 80 |  81 82A few other algorithms can produce higher compression ratios at slower speeds, falling outside of the graph. 83For a larger picture including slow modes, [click on this link](doc/images/DCspeed5.png). 84 85 86## The case for Small Data compression 87 88Previous charts provide results applicable to typical file and stream scenarios (several MB). Small data comes with different perspectives. 89 90The smaller the amount of data to compress, the more difficult it is to compress. This problem is common to all compression algorithms, and reason is, compression algorithms learn from past data how to compress future data. But at the beginning of a new data set, there is no "past" to build upon. 91 92To solve this situation, Zstd offers a __training mode__, which can be used to tune the algorithm for a selected type of data. 93Training Zstandard is achieved by providing it with a few samples (one file per sample). The result of this training is stored in a file called "dictionary", which must be loaded before compression and decompression. 94Using this dictionary, the compression ratio achievable on small data improves dramatically. 95 96The following example uses the `github-users` [sample set](https://github.com/facebook/zstd/releases/tag/v1.1.3), created from [github public API](https://developer.github.com/v3/users/#get-all-users). 97It consists of roughly 10K records weighing about 1KB each. 98 99Compression Ratio | Compression Speed | Decompression Speed 100------------------|-------------------|-------------------- 101 |  |  102 103 104These compression gains are achieved while simultaneously providing _faster_ compression and decompression speeds. 105 106Training works if there is some correlation in a family of small data samples. The more data-specific a dictionary is, the more efficient it is (there is no _universal dictionary_). 107Hence, deploying one dictionary per type of data will provide the greatest benefits. 108Dictionary gains are mostly effective in the first few KB. Then, the compression algorithm will gradually use previously decoded content to better compress the rest of the file. 109 110### Dictionary compression How To: 111 1121. Create the dictionary 113 114 `zstd --train FullPathToTrainingSet/* -o dictionaryName` 115 1162. Compress with dictionary 117 118 `zstd -D dictionaryName FILE` 119 1203. Decompress with dictionary 121 122 `zstd -D dictionaryName --decompress FILE.zst` 123 124 125## Build instructions 126 127### Makefile 128 129If your system is compatible with standard `make` (or `gmake`), 130invoking `make` in root directory will generate `zstd` cli in root directory. 131 132Other available options include: 133- `make install` : create and install zstd cli, library and man pages 134- `make check` : create and run `zstd`, tests its behavior on local platform 135 136### cmake 137 138A `cmake` project generator is provided within `build/cmake`. 139It can generate Makefiles or other build scripts 140to create `zstd` binary, and `libzstd` dynamic and static libraries. 141 142By default, `CMAKE_BUILD_TYPE` is set to `Release`. 143 144### Meson 145 146A Meson project is provided within [`build/meson`](build/meson). Follow 147build instructions in that directory. 148 149You can also take a look at [`.travis.yml`](.travis.yml) file for an 150example about how Meson is used to build this project. 151 152Note that default build type is **release**. 153 154### VCPKG 155You can build and install zstd [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager: 156 157 git clone https://github.com/Microsoft/vcpkg.git 158 cd vcpkg 159 ./bootstrap-vcpkg.sh 160 ./vcpkg integrate install 161 ./vcpkg install zstd 162 163The zstd port in vcpkg is kept up to date by Microsoft team members and community contributors. 164If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository. 165 166### Visual Studio (Windows) 167 168Going into `build` directory, you will find additional possibilities: 169- Projects for Visual Studio 2005, 2008 and 2010. 170 + VS2010 project is compatible with VS2012, VS2013, VS2015 and VS2017. 171- Automated build scripts for Visual compiler by [@KrzysFR](https://github.com/KrzysFR), in `build/VS_scripts`, 172 which will build `zstd` cli and `libzstd` library without any need to open Visual Studio solution. 173 174### Buck 175 176You can build the zstd binary via buck by executing: `buck build programs:zstd` from the root of the repo. 177The output binary will be in `buck-out/gen/programs/`. 178 179## Testing 180 181You can run quick local smoke tests by executing the `playTest.sh` script from the `src/tests` directory. 182Two env variables `$ZSTD_BIN` and `$DATAGEN_BIN` are needed for the test script to locate the zstd and datagen binary. 183For information on CI testing, please refer to TESTING.md 184 185## Status 186 187Zstandard is currently deployed within Facebook. It is used continuously to compress large amounts of data in multiple formats and use cases. 188Zstandard is considered safe for production environments. 189 190## License 191 192Zstandard is dual-licensed under [BSD](LICENSE) and [GPLv2](COPYING). 193 194## Contributing 195 196The `dev` branch is the one where all contributions are merged before reaching `release`. 197If you plan to propose a patch, please commit into the `dev` branch, or its own feature branch. 198Direct commit to `release` are not permitted. 199For more information, please read [CONTRIBUTING](CONTRIBUTING.md). 200
