1lz4(1) -- lz4, unlz4, lz4cat - Compress or decompress .lz4 files 2================================================================ 3 4SYNOPSIS 5-------- 6 7`lz4` [*OPTIONS*] [-|INPUT-FILE] <OUTPUT-FILE> 8 9`unlz4` is equivalent to `lz4 -d` 10 11`lz4cat` is equivalent to `lz4 -dcfm` 12 13When writing scripts that need to decompress files, 14it is recommended to always use the name `lz4` with appropriate arguments 15(`lz4 -d` or `lz4 -dc`) instead of the names `unlz4` and `lz4cat`. 16 17 18DESCRIPTION 19----------- 20 21`lz4` is a CLI based on `liblz4`, an extremely fast implementation of lossless compression algorithm. 22It provides a default compression speed of typically > 500 MB/s per core. 23Speed can traded for higher compression ratio, by increasing the compression level parameter. 24While decompression is single-threaded, it reaches multiple GB/s, generally fast enough to be I/O bound. 25`lz4` native file format is the `.lz4` format. 26 27### Difference between lz4 and gzip 28 29`lz4` supports a command line syntax similar _but not identical_ to `gzip(1)`. 30Differences are : 31 32 * `lz4` compresses a single file by default (see `-m` for multiple files) 33 * `lz4 file1 file2` means : compress file1 _into_ file2 34 * `lz4 file.lz4` will default to decompression (use `-z` to force compression) 35 * `lz4` preserves original files (see `--rm` to erase source file on completion) 36 * `lz4` shows real-time notification statistics 37 during compression or decompression of a single file 38 (use `-q` to silence them) 39 * When no destination is specified, result is sent on implicit output, 40 which depends on `stdout` status. 41 When `stdout` _is Not the console_, it becomes the implicit output. 42 Otherwise, if `stdout` is the console, the implicit output is `filename.lz4`. 43 * It is considered bad practice to rely on implicit output in scripts. 44 because the script's environment may change. 45 Always use explicit output in scripts. 46 `-c` ensures that output will be `stdout`. 47 Conversely, providing a destination name, or using `-m` 48 ensures that the output will be either the specified name, or `filename.lz4` respectively. 49 50Default behaviors can be modified by opt-in commands, detailed below. 51 52 * `lz4 -m` makes it possible to provide multiple input filenames, 53 which will be compressed into files using suffix `.lz4`. 54 Progress notifications become disabled by default (use `-v` to enable them). 55 This mode has a behavior which more closely mimics `gzip` command line, 56 with the main remaining difference being that source files are preserved by default. 57 * Similarly, `lz4 -m -d` can decompress multiple `*.lz4` files. 58 * It's possible to opt-in to erase source files 59 on successful compression or decompression, using `--rm` command. 60 * Consequently, `lz4 -m --rm` features a behavior closer to the `gzip` one. 61 62### Concatenation of .lz4 files 63 64It is possible to concatenate `.lz4` files as is. 65`lz4` will decompress such files as if they were a single `.lz4` file. 66For example: 67 68 lz4 file1 > foo.lz4 69 lz4 file2 >> foo.lz4 70 71Then `lz4cat foo.lz4` is equivalent to `cat file1 file2`. 72 73OPTIONS 74------- 75 76### Short commands concatenation 77 78In some cases, some options can be expressed using short command `-x` 79or long command `--long-word`. 80Short commands can be concatenated together. 81For example, `-d -c` is equivalent to `-dc`. 82Long commands cannot be concatenated. They must be clearly separated by a space. 83 84### Multiple commands 85 86When multiple contradictory commands are issued on a same command line, 87only the latest one will be applied. 88 89### Operation mode 90 91* `-z` `--compress`: 92 Compress. 93 This is the default operation mode when no operation mode option is 94 specified, no other operation mode is implied from the command name 95 (for example, `unlz4` implies `--decompress`), 96 nor from the input file name 97 (for example, a file extension `.lz4` implies `--decompress` by default). 98 `-z` can also be used to force compression of an already compressed 99 `.lz4` file. 100 101* `-d` `--decompress` `--uncompress`: 102 Decompress. 103 `--decompress` is also the default operation when the input filename has an 104 `.lz4` extension. 105 106* `-t` `--test`: 107 Test the integrity of compressed `.lz4` files. 108 The decompressed data is discarded. 109 No files are created nor removed. 110 111* `-b#`: 112 Benchmark mode, using `#` compression level. 113 114* `--list`: 115 List information about .lz4 files. 116 For detailed information on files with multiple frames, use `-v`. 117 `--list` automatically triggers `-m` modifier. 118 119### Operation modifiers 120 121* `-#`: 122 Compression level, with # being any value from 1 to 12. 123 Higher values trade compression speed for compression ratio. 124 Values above 12 are considered the same as 12. 125 Recommended values are 1 for fast compression (default), 126 and 9 for high compression. 127 Speed/compression trade-off will vary depending on data to compress. 128 Decompression speed remains fast at all settings. 129 130* `--fast[=#]`: 131 Switch to ultra-fast compression levels. 132 The higher the value, the faster the compression speed, at the cost of some compression ratio. 133 If `=#` is not present, it defaults to `1`. 134 This setting overrides compression level if one was set previously. 135 Similarly, if a compression level is set after `--fast`, it overrides it. 136 137* `--best`: 138 Set highest compression level. Same as -12. 139 140* `-T#`, `--threads=#`: 141 Use `#` threads for compression. 142 When `0`, or none provided: automatically determined from nb of detected cores. 143 144* `--favor-decSpeed`: 145 Generate compressed data optimized for decompression speed. 146 Compressed data will be larger as a consequence (typically by ~0.5%), 147 while decompression speed will be improved by 5-20%, depending on use cases. 148 This option only works in combination with very high compression levels (>=10). 149 150* `-D dictionaryName`: 151 Compress, decompress or benchmark using dictionary _dictionaryName_. 152 Compression and decompression must use the same dictionary to be compatible. 153 Using a different dictionary during decompression will either 154 abort due to decompression error, or generate a checksum error. 155 156* `-f` `--[no-]force`: 157 This option has several effects: 158 159 If the target file already exists, overwrite it without prompting. 160 161 When used with `--decompress` and `lz4` cannot recognize the type of 162 the source file, copy the source file as is to standard output. 163 This allows `lz4cat --force` to be used like `cat (1)` for files 164 that have not been compressed with `lz4`. 165 166* `-c` `--stdout` `--to-stdout`: 167 Force write to standard output, even if it is the console. 168 169* `-m` `--multiple`: 170 Multiple input files. 171 Compressed file names will be appended a `.lz4` suffix. 172 This mode also reduces notification level. 173 Can also be used to list multiple files. 174 `lz4 -m` has a behavior equivalent to `gzip -k` 175 (it preserves source files by default). 176 177* `-r` : 178 operate recursively on directories. 179 This mode also sets `-m` (multiple input files). 180 181* `-B#`: 182 Block size \[4-7\](default : 7)<br/> 183 `-B4`= 64KB ; `-B5`= 256KB ; `-B6`= 1MB ; `-B7`= 4MB 184 185* `-BI`: 186 Produce independent blocks (default) 187 188* `-BD`: 189 Blocks depend on predecessors (improves compression ratio, more noticeable on small blocks) 190 191* `-BX`: 192 Generate block checksums (default:disabled) 193 194* `--[no-]frame-crc`: 195 Select frame checksum (default:enabled) 196 197* `--no-crc`: 198 Disable both frame and block checksums 199 200* `--[no-]content-size`: 201 Header includes original size (default:not present)<br/> 202 Note : this option can only be activated when the original size can be 203 determined, hence for a file. It won't work with unknown source size, 204 such as stdin or pipe. 205 206* `--[no-]sparse`: 207 Sparse mode support (default:enabled on file, disabled on stdout) 208 209* `-l`: 210 Use Legacy format (typically for Linux Kernel compression)<br/> 211 Note : `-l` is not compatible with `-m` (`--multiple`) nor `-r` 212 213### Other options 214 215* `-v` `--verbose`: 216 Verbose mode 217 218* `-q` `--quiet`: 219 Suppress warnings and real-time statistics; 220 specify twice to suppress errors too 221 222* `-h` `-H` `--help`: 223 Display help/long help and exit 224 225* `-V` `--version`: 226 Display Version number and exit 227 228* `-k` `--keep`: 229 Preserve source files (default behavior) 230 231* `--rm` : 232 Delete source files on successful compression or decompression 233 234* `--` : 235 Treat all subsequent arguments as files 236 237 238### Benchmark mode 239 240* `-b#`: 241 Benchmark file(s), using # compression level 242 243* `-e#`: 244 Benchmark multiple compression levels, from b# to e# (included) 245 246* `-i#`: 247 Minimum evaluation time in seconds \[1-9\] (default : 3) 248 249 250### Environment Variables 251 252It's possible to pass some parameters to `lz4` via environment variables. 253This can be useful in situations where `lz4` is known to be invoked (from a script for example) but there is no way to pass `lz4` parameters to influence the compression session. 254The environment variable has higher priority than executable default, but lower priority than corresponding runtime command. 255When set as global environment variables, it can be a way to enforce personalized defaults different from the executable set ones. 256 257* `LZ4_CLEVEL`: 258 specify a default compression level that `lz4` employs for compression when no other compression level is specified on command line. Executable default is generally `1`. 259 260* `LZ4_NBWORKERS`: 261 specify a default number of threads that `lz4` will employ for compression. Executable default is generally `0`, which means auto-determined based on local cpu. This functionality is only relevant when `lz4` is compiled with multithreading support. The maximum number of workers is capped at `LZ4_NBWORKERS_MAX` (`200` by default). 262 263 264BUGS 265---- 266 267Report bugs at: https://github.com/lz4/lz4/issues 268 269 270AUTHOR 271------ 272 273Yann Collet 274