Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
LZ4(1)				 User Commands				LZ4(1)

       lz4 - lz4, unlz4, lz4cat	- Compress or decompress .lz4 files


       unlz4 is	equivalent to lz4 -d

       lz4cat is equivalent to lz4 -dcfm

       When  writing  scripts that need	to decompress files, it	is recommended
       to always use the name lz4 with appropriate arguments (lz4  -d  or  lz4
       -dc) instead of the names unlz4 and lz4cat.

       lz4  is	an  extremely  fast  lossless  compression algorithm, based on
       byte-aligned LZ77 family	of compression scheme. lz4 offers  compression
       speeds of 400 MB/s per core, linearly scalable with multi-core CPUs. It
       features	an extremely fast decoder, with	speed  in  multiple  GB/s  per
       core, typically reaching	RAM speed limit	on multi-core systems. The na-
       tive file format	is the .lz4 format.

   Difference between lz4 and gzip
       lz4 supports a  command	line  syntax  similar  but  not	 identical  to
       gzip(1).	Differences are	:

       o   lz4 compresses a single file	by default (see	-m for multiple	files)

       o   lz4 file1 file2 means : compress file1 into file2

       o   lz4	file.lz4  will	default	to decompression (use -z to force com-

       o   lz4 preserves original files

       o   lz4 shows real-time notification statistics during  compression  or
	   decompression of a single file (use -q to silence them)

       o   When	 no  destination is specified, result is sent on implicit out-
	   put,	which depends on stdout	status.	When stdout is	Not  the  con-
	   sole,  it  becomes the implicit output. Otherwise, if stdout	is the
	   console, the	implicit output	is filename.lz4.

       o   It is considered  bad  practice  to	rely  on  implicit  output  in
	   scripts.  because  the  script's environment	may change. Always use
	   explicit output in scripts. -c ensures that output will be  stdout.
	   Conversely,	providing a destination	name, or using -m ensures that
	   the output will be either the specified name, or  filename.lz4  re-

       Default behaviors can be	modified by opt-in commands, detailed below.

       o   lz4 -m makes	it possible to provide multiple	input filenames, which
	   will	be compressed into files using suffix .lz4. Progress notifica-
	   tions become	disabled by default (use -v to enable them). This mode
	   has a behavior which	more closely mimics gzip  command  line,  with
	   the main remaining difference being that source files are preserved
	   by default.

       o   Similarly, lz4 -m -d	can decompress multiple	*.lz4 files.

       o   It's	possible to opt-in to erase source files  on  successful  com-
	   pression or decompression, using --rm command.

       o   Consequently, lz4 -m	--rm behaves the same as gzip.

   Concatenation of .lz4 files
       It  is  possible	 to  concatenate .lz4 files as is. lz4 will decompress
       such files as if	they were a single .lz4	file. For example:

	   lz4 file1  >	foo.lz4
	   lz4 file2 >>	foo.lz4

       Then lz4cat foo.lz4 is equivalent to cat	file1 file2.

   Short commands concatenation
       In some cases, some options can be expressed using short	command	-x  or
       long  command --long-word. Short	commands can be	concatenated together.
       For example, -d -c is equivalent	to -dc.	Long commands cannot  be  con-
       catenated. They must be clearly separated by a space.

   Multiple commands
       When multiple contradictory commands are	issued on a same command line,
       only the	latest one will	be applied.

   Operation mode
       -z --compress
	      Compress.	This is	the default operation mode when	 no  operation
	      mode  option  is	specified,  no other operation mode is implied
	      from the command name (for example, unlz4	implies	--decompress),
	      nor from the input file name (for	example, a file	extension .lz4
	      implies --decompress by default).	-z can also be used  to	 force
	      compression of an	already	compressed .lz4	file.

       -d --decompress --uncompress
	      Decompress.  --decompress	is also	the default operation when the
	      input filename has an .lz4 extension.

       -t --test
	      Test the integrity of compressed .lz4  files.  The  decompressed
	      data is discarded. No files are created nor removed.

       -b#    Benchmark	mode, using # compression level.

       --list List information about .lz4 files. note :	current	implementation
	      is limited to single-frame .lz4 files.

   Operation modifiers
       -#     Compression level, with #	being any value	from 1 to  12.	Higher
	      values  trade  compression  speed	 for compression ratio.	Values
	      above 12 are considered the same as 12. Recommended values are 1
	      for  fast	 compression  (default),  and  9 for high compression.
	      Speed/compression	trade-off will vary depending on data to  com-
	      press. Decompression speed remains fast at all settings.

	      Switch  to  ultra-fast compression levels. The higher the	value,
	      the faster the compression speed,	at the cost of	some  compres-
	      sion ratio. If =#	is not present,	it defaults to 1. This setting
	      overrides	compression level if one  was  set  previously.	 Simi-
	      larly,  if a compression level is	set after --fast, it overrides

       --best Set highest compression level. Same as -12.

	      Generate compressed data optimized for decompression speed. Com-
	      pressed  data  will  be  larger  as  a consequence (typically by
	      ~0.5%), while decompression speed	will be	improved by 5-20%, de-
	      pending on use cases. This option	only works in combination with
	      very high	compression levels (>=10).

       -D dictionaryName
	      Compress,	decompress or benchmark	using  dictionary  dictionary-
	      Name. Compression	and decompression must use the same dictionary
	      to be compatible.	Using a	different dictionary during decompres-
	      sion will	either abort due to decompression error, or generate a
	      checksum error.

       -f --[no-]force
	      This option has several effects:

	      If the target file already exists, overwrite it without  prompt-

	      When used	with --decompress and lz4 cannot recognize the type of
	      the source file, copy the	source file as is to standard  output.
	      This  allows  lz4cat  --force  to	be used	like cat (1) for files
	      that have	not been compressed with lz4.

       -c --stdout --to-stdout
	      Force write to standard output, even if it is the	console.

       -m --multiple
	      Multiple input files. Compressed file names will be  appended  a
	      .lz4 suffix. This	mode also reduces notification level. Can also
	      be used to list multiple files. lz4 -m has a behavior equivalent
	      to gzip -k (it preserves source files by default).

       -r     operate recursively on directories. This mode also sets -m (mul-
	      tiple input files).

       -B#    Block size [4-7](default : 7)
	      -B4= 64KB	; -B5= 256KB ; -B6= 1MB	; -B7= 4MB

       -BI    Produce independent blocks (default)

       -BD    Blocks depend on predecessors (improves compression ratio,  more
	      noticeable on small blocks)

	      Select frame checksum (default:enabled)

	      Header includes original size (default:not present)
	      Note  : this option can only be activated	when the original size
	      can be determined, hence for a file. It won't work with  unknown
	      source size, such	as stdin or pipe.

	      Sparse  mode  support (default:enabled on	file, disabled on std-

       -l     Use Legacy format	(typically for Linux Kernel compression)
	      Note : -l	is not compatible with -m (--multiple) nor -r

   Other options
       -v --verbose
	      Verbose mode

       -q --quiet
	      Suppress warnings	and real-time  statistics;  specify  twice  to
	      suppress errors too

       -h -H --help
	      Display help/long	help and exit

       -V --version
	      Display Version number and exit

       -k --keep
	      Preserve source files (default behavior)

       --rm   Delete source files on successful	compression or decompression

       --     Treat all	subsequent arguments as	files

   Benchmark mode
       -b#    Benchmark	file(s), using # compression level

       -e#    Benchmark	multiple compression levels, from b# to	e# (included)

       -i#    Minimum evaluation time in seconds [1-9] (default	: 3)

       Report bugs at:

       Yann Collet

lz4 1.9.2			   July	2019				LZ4(1)


Want to link to this manual page? Use this URL:

home | help